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

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

仕組み

すべてのエージェントは同じコンテナとファイルシステムを共有しますが、各エージェントは独自のセッションスレッドで実行されます。スレッドは、独自の会話履歴を持つコンテキスト分離されたイベントストリームです。コーディネーターはプライマリスレッド（セッションレベルのイベントストリームと同じ）でアクティビティをレポートします。追加のスレッドは、コーディネーターが委任を決定したときに実行時に生成されます。

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

各エージェントは、そのエージェントが作成されたときに定義された独自の設定（モデル、システムプロンプト、ツール、MCPサーバー、スキル）を使用します。ツールとコンテキストは共有されません。

委任する内容

マルチエージェントセッションは、全体的な目標の中に複数の適切にスコープされた特化したタスクがある場合に最適に機能します。

• コードレビュー： フォーカスされたシステムプロンプトと読み取り専用ツールを備えたレビュアーエージェント。
• テスト生成： 本番コードに触れずにテストを作成して実行するテストエージェント。
• リサーチ： Webツールを備えた検索エージェントが、コーディネーターに調査結果をまとめて報告します。

呼び出し可能なエージェントを宣言する

エージェントを定義する際に、呼び出しが許可されている他のエージェントのIDをリストします。

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

callable_agentsの各エントリは、既存のエージェントのIDである必要があります。委任は1レベルのみサポートされています。コーディネーターは他のエージェントを呼び出すことができますが、それらのエージェント自体は他のエージェントを呼び出すことはできません。

次に、オーケストレーターを参照するセッションを作成します。

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

呼び出し可能なエージェントはオーケストレーターの設定から解決されます。セッション作成時にそれらを参照する必要はありません。

セッションスレッド

セッションレベルのイベントストリーム（/v1/sessions/:id/stream）はプライマリスレッドと見なされ、すべてのスレッド全体のすべてのアクティビティの圧縮ビューが含まれます。呼び出されたエージェントの個別のトレースは表示されませんが、それらの作業の開始と終了は表示されます。セッションスレッドは、特定のエージェントの推論とツール呼び出しを詳しく調べる場所です。

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

セッション内のすべてのスレッドをリストするには、以下のようにします。

for thread in client.beta.sessions.threads.list(session.id):
    print(f"[{thread.agent_name}] {thread.status}")

特定のスレッドからイベントをストリーミングします。

with client.beta.sessions.threads.stream(
    thread.id,
    session_id=session.id,
) as stream:
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    if block.type == "text":
                        print(block.text, end="")
            case "session.thread_idle":
                break

スレッドの過去のイベントをリストします。

for event in client.beta.sessions.threads.events.list(
    thread.id,
    session_id=session.id,
):
    print(f"[{event.type}] {event.processed_at}")

マルチエージェントイベントタイプ

これらのイベントは、トップレベルのセッションストリーム上のマルチエージェントアクティビティを表示します。

スレッド内のツール権限とカスタムツール

callable_agentスレッドがクライアントから何かが必要な場合（always_askツールを実行する権限、またはカスタムツール呼び出しの結果）、リクエストはセッションストリームにsession_thread_idフィールドで表示されます。応答を投稿するときに同じsession_thread_idを含めて、プラットフォームがそれを待機中のスレッドにルーティングするようにします。

• session_thread_idが存在する： イベントはサブエージェントスレッドから発生しました。返信でそれをエコーします。
• session_thread_idが存在しない： イベントはプライマリスレッドから来ました。フィールドなしで返信します。
• tool_use_idでマッチングして、リクエストと応答をペアリングします。

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

for event_id in stop.event_ids:
    pending = events_by_id[event_id]
    confirmation = {
        "type": "user.tool_confirmation",
        "tool_use_id": event_id,
        "result": "allow",
    }
    # Echo session_thread_id when the request came from a subagent thread
    if pending.session_thread_id is not None:
        confirmation["session_thread_id"] = pending.session_thread_id
    client.beta.sessions.events.send(session.id, events=[confirmation])