マルチエージェントセッション

マルチエージェントオーケストレーションにより、1つのエージェントが他のエージェントと連携して複雑な作業を完了できます。各エージェントは独自の分離されたコンテキストで並行して動作できるため、出力品質の向上や完了までの時間短縮に役立ちます。



仕組み

すべてのエージェントは同じサンドボックス、ファイルシステム、およびボールト認証情報を共有しますが、各エージェントは独自のセッションスレッド（session thread）で実行されます。これは、独自の会話履歴を持つコンテキスト分離されたイベントストリームです。コーディネーターはプライマリスレッド（セッションレベルのイベントストリームと同じもの）でアクティビティを報告します。追加のスレッドは、コーディネーターが作業を委任する際に実行時に生成されます。

スレッドは永続的です。コーディネーターは以前に呼び出したエージェントにフォローアップを送信でき、そのエージェントは以前のターンのすべての内容を保持しています。

各エージェントは独自の設定（モデル、システムプロンプト、ツール、MCPサーバー、スキル）を使用します。セッションレベルのエージェント設定オーバーライドは例外で、コーディネーターとそのselfコピーに適用されます。ツール、MCPサーバー、コンテキストは共有されません。



委任すべき内容

マルチエージェント調整は、さまざまな領域にまたがる作業が必要な複雑なタスク、または複数の明確にスコープされたタスクが全体的な目標に貢献するような複雑なタスクに最適です。

うまく機能するパターン：

• 並列化： 独立したサブタスク（複数のソースの検索、個別のファイルの分析など）を同時に展開し、コーディネーターに結果を統合させます。
• 専門化： 単一のエージェントにすべての機能を詰め込むのではなく、セキュリティエージェントやドキュメントエージェントなど、ドメインに特化したシステムプロンプトとツールを持つエージェントにルーティングします。
• エスカレーション： 複雑なサブタスクの一部について、より高性能なエージェントまたはモデルに相談します。



コーディネーターの設定

エージェントを定義する際に、multiagentを設定して、コーディネーターが委任できるエージェントのロスターを宣言します。

ant beta:agents create <<YAML
name: Engineering Lead
model: claude-opus-4-8
system: You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.
tools:
  - type: agent_toolset_20260401
multiagent:
  type: coordinator
  agents:
    - type: agent
      id: $REVIEWER_AGENT_ID
    - type: agent
      id: $TEST_WRITER_AGENT_ID
YAML

multiagent.agentsは以下のいずれかを受け入れます。

• {"type": "agent", "id": agent.id}は、以前に作成されたagentをIDで参照します。versionが指定されていない場合、参照はコーディネーター作成時点でのそのエージェントの最新バージョンに固定されます。
• {"type": "agent", "id": agent.id, "version": agent.version}は、特定のエージェントバージョンに固定します。
• {"type": "self"}は、コーディネーターが自身のコピーを生成できるようにします。セッションがエージェント設定オーバーライド付きで作成された場合、それらのオーバーライドはこれらのコピーにも適用されます。IDで参照されるロスターエントリは影響を受けません。

コーディネーターの設定（multiagent.agentsロスターを含む）は、コーディネーターの作成時または更新時にスナップショットされます。参照されるエージェントはその時点で解決されたバージョンに固定されたままとなり、それらの定義に対する後の更新を自動的に取り込むことはありません。参照されるエージェントの新しいバージョンに委任するには、コーディネーターを更新して、そのロスターがそのバージョンを参照するようにします。

コーディネーターは1階層のエージェントにのみ委任できます。深さが1を超える場合は無視されます。multiagent.agentsには最大20個の一意のエージェントをリストできますが、コーディネーターは各エージェントの複数のコピーを呼び出すことができます。



セッションの作成

コーディネーターを参照するセッションを作成します。コーディネーターは必要に応じてロスター内のエージェントに委任します。

session = client.beta.sessions.create(
    agent=coordinator.id,
    environment_id=environment.id,
)



エージェントをMCPサーバーに接続する

MCPサーバーはエージェントスコープ（各エージェント定義が独自のサーバーとツールを宣言）であり、ボールト認証情報はセッションスコープ（セッション作成時に渡されるvault_idsがすべてのスレッドに適用）です。統合における2つの注意点：

• MCPサーバーを認証するには、すべてのエージェントで使用されるすべてのMCPサーバーに対してボールト認証情報を含めます。
• エージェントのアクセスを制限するには、そのエージェント定義で必要なサーバーのみを宣言します。

セッション作成時のエージェント設定オーバーライドにより、コーディネーターとそのselfコピーのMCPサーバーを置き換えることができます。

research_agent = client.beta.agents.create(
    name="researcher",
    model="claude-haiku-4-5",
    mcp_servers=[
        {"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"},
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "github"}],
)

coordinator = client.beta.agents.create(
    name="coordinator",
    model="claude-opus-4-8",
    tools=[{"type": "agent_toolset_20260401"}],
    multiagent={
        "type": "coordinator",
        "agents": [{"type": "agent", "id": research_agent.id}],
    },
)

session = client.beta.sessions.create(
    agent=coordinator.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)
print(session.id)

この例では、リサーチャーのみがGitHub MCPサーバーを宣言しているため、コーディネーターはアクセスできません。セッションのvault_idsがリサーチャーのスレッドにGitHub認証情報を提供します。



スレッド

セッションレベルのイベントストリーム（/v1/sessions/:id/events/stream）はプライマリスレッドとみなされ、すべてのスレッドにわたるすべてのアクティビティの要約ビューを含みます。サブエージェントからの完全なアクティビティは表示されませんが、その作業の開始と終了、およびツール権限リクエストなどのブロッキングイベントは表示されます。

セッションスレッドは、特定のエージェントのアクティビティを詳しく調べる場所です。

セッションのstatusはすべてのエージェントアクティビティの集約です。少なくとも1つのスレッドがrunningの場合、セッション全体のステータスもrunningになります。



プライマリスレッドイベント

これらのイベントは、/v1/sessions/:id/events/streamのプライマリスレッドでマルチエージェントアクティビティを表示します。



セッションスレッドイベント

重要なイベントはプライマリスレッドにプロキシされます。ただし、特定のエージェントの推論やツール呼び出しを調査したい場合もあります。その場合は、関連するセッションスレッドからイベントをストリーミングまたは一覧表示します。



ツール権限とカスタムツール

サブエージェントがクライアントから何かを必要とする場合（always_askツールを実行するための権限や、カスタムツールの結果など）、そのイベントは発信元のセッションスレッドを識別するsession_thread_idとともにプライマリスレッドにクロスポストされます。

{
  "type": "session.thread_status_idle",
  "id": "sevt_01ABC...",
  "session_thread_id": "sth_01DEF...",
  "agent_name": "code-reviewer",
  "stop_reason": {
    "type": "requires_action",
    "event_ids": ["toolu_01XYZ..."]
  }
}

user.tool_confirmation（tool_use_id付き）またはuser.custom_tool_result（custom_tool_use_id付き）を投稿します。サーバーは応答を正しいスレッドに自動的にルーティングします。

次の例は、ツール確認ハンドラーを拡張して返信をルーティングします。同じパターンがuser.custom_tool_resultにも適用されます。

for event_id in stop.event_ids:
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.tool_confirmation",
                "tool_use_id": event_id,
                "result": "allow",
            }
        ],
    )