ランツリーとストリーミングトポロジー

Goa-AIがエージェントランをツリーとしてモデル化する方法と、ストリーミングがそのトポロジーを異なるオーディエンスにどのように投影するかを理解する。

ラン、セッション、ランツリー

Goa-AIは実行をランとツールのツリーとしてモデル化します：

  • ラン – エージェントの1回の実行：

    • RunIDで識別、
    • run.Context（RunID、SessionID、TurnID、ラベル、キャップ）で記述、
    • run.Record（ステータス、タイムスタンプ、ラベル）で永続的に追跡。

  • セッション – 1つ以上のランにまたがる会話またはワークフロー：

    • SessionIDが関連ランをグループ化（例：マルチターンチャット）。
    • UIは通常、一度に1つのセッションをレンダリングします。

  • ランツリー – ランとツール間の親子関係：

    • トップレベルのエージェントラン（例：chat）、
    • 子エージェントラン（エージェントアズツール、例：ada、diagnostics）、
    • それらのエージェントの下にあるサービスツール。

ランタイムはこのツリーを以下を使用して維持します：

  • run.Handle – 軽量ハンドル：RunID、AgentID、ParentRunID、ParentToolCallID。
  • ネストされたエージェントに対して常に実際の子ランを作成するエージェントアズツールヘルパーとツールセット登録（隠れたインラインハックなし）。

エージェントが別のエージェントをツールとして使用する場合：

  • ランタイムは：
    • 独自のRunIDを持つプロバイダーエージェントの子ランを開始、
    • run.Contextで親子リンクを追跡、
    • 子で完全なプラン/実行/再開ループを実行。
  • 親ツール結果（planner.ToolResult）は以下を持ちます：
RunLink *run.Handle

このRunLinkにより：

  • プランナーが子ランについて推論（例：監査/ログ用）、
  • UIが子ランのストリームにサブスクライブできるネストされた「エージェントカード」を作成、
  • 外部ツールが推測なしに親ランから子へナビゲート。

ランごとのストリーム、グローバルファイアホースではない

各ランは独自のstream.Event値のストリームを持ちます：

  • AssistantReply、PlannerThought、
  • ToolStart、ToolUpdate、ToolEnd、
  • AwaitClarification、AwaitExternalTools、
  • Usage、Workflow、
  • AgentRunStarted（親ツール → 子ランへのリンク）。

コンシューマーはランごとにサブスクライブします：

sink := &MySink{}
stop, err := rt.SubscribeRun(ctx, runID, sink)
if err != nil { /* 処理 */ }
defer stop()

これによりグローバルファイアホースを回避し、UIは：

  • ランごとに1接続（例：チャットセッションごと）をアタッチ、
  • AgentRunStartedメタデータ（ChildRunID、ChildAgentID）を使用してランにサブスクライブすることで子エージェントに「ドリルイン」するタイミングを決定。

ストリームプロファイルと子ポリシー

stream.StreamProfileはオーディエンスが見るものを記述します：

  • どのイベント種別が含まれるか、
  • 子ランがChildStreamPolicyを介してどのように投影されるか：
    • Off – このオーディエンスから子ランを隠す。親ツールコール/結果のみ。
    • Flatten – 子イベントを親ストリームに投影（デバッグスタイルの「ファイアホース」）。
    • Linked – 親がAgentRunStartedリンクイベントを発行。子イベントは独自のストリームに残る。

組み込みプロファイル：

  • stream.UserChatProfile() – エンドユーザーチャット向け
  • stream.AgentDebugProfile() – 詳細な運用ビュー
  • stream.MetricsProfile() – メトリクス/テレメトリ

これがUI設計にどう役立つか

ランツリー + ストリーミングモデルにより、典型的なチャットUIは：

  • ユーザーチャットプロファイルでルートチャットランにサブスクライブ、
  • レンダリング：アシスタント返信、トップレベルツールのツール行、ネストされたエージェントカードとしての「エージェントラン開始」イベント、
  • ユーザーがカードを展開すると：ChildRunIDを使用して子ランにサブスクライブ、そのエージェント独自のタイムラインをカード内にレンダリング。

キーアイデア：実行トポロジー（ランツリー）は常に保持され、ストリーミングは異なるオーディエンス向けのそのツリー上の投影のセットです。