マルチエージェントオーケストレーション

「multiagent orchestration」（マルチエージェントオーケストレーション）により、1つのエージェントが他のエージェントと連携して複雑な作業を完了できます。エージェントはそれぞれ独立したコンテキストを持って並列に動作できるため、出力品質の向上に役立ち、完了までの時間も短縮できる場合があります。

マルチエージェント構成が自分の課題に適しているかわからない場合は、マルチエージェントシステムを使うべきとき（と使うべきでないとき）を参照してください。

他のエージェントに作業を引き渡す

セッションが実行するエージェントは、2つの方法で他のエージェントに作業を引き渡すことができます。「subagents」（サブエージェント）を使う場合、エージェント自身がタスクを委任し、各サブエージェントが報告する内容を読み取ります。「dynamic workflows」（動的ワークフロー）を使う場合、エージェントはワークフローを作成します。これは、多数のエージェントをバックグラウンドで実行し、その結果を統合するプログラムです。また、エージェントは自ら作業を行いながら、ガイダンスを得るために「advisor」（アドバイザー）モデルに相談することもできます。

エージェントがこれらのうちどれを使用できるかはあなたが決め、いつ使用するかはエージェントが判断します。その選択を導くには、システムプロンプトでワークフロー実行をいつ使用すべきかをエージェントに伝えてください。実行を使用するタイミングをエージェントに伝えるを参照してください。また、エージェントが使用できるエージェントを、あなたが列挙したものに限定することもできます。

サブエージェントの場合、次に何が起こるかはエージェント自身が判断します。サブエージェントのスレッドはアーカイブするまで利用可能なままなので、エージェントはフォローアップメッセージを送信できます。動的ワークフローの場合、Claudeは、Claudeが直接関与することなくエージェントをオーケストレーションするプログラムを作成します。コンテキストと結果はエージェントからエージェントへプログラム的に受け渡されるため、メインのセッションスレッドはユーザーとのコミュニケーションや、実行中の1つまたは複数のワークフローの状況確認と進捗報告に専念できます。エージェントは実行のスレッドにフォローアップメッセージを送信できず、サーバーは各スレッドを実行の終了までにアーカイブします。

これらは、エージェント定義の multiagent ブロックで設定します。このブロックには type があります。multiagent_20261001 タイプでは、エージェントは3つすべてを併用でき、それぞれをオンまたはオフにできます。デフォルトでは、subagents と workflows の両方が有効です。subagents と workflows はそれぞれ inline_agents が有効になっています。これはエージェントまたはワークフローが自ら定義するエージェントのための設定です：

{
  "multiagent": { "type": "multiagent_20261001" }
}

エージェントが呼び出せるエージェントを設定するには、事前定義エージェントとインラインエージェントを参照してください。設定をオフにするには、動的ワークフローを有効にするを参照してください。

事前定義エージェントとインラインエージェント

すべてのサブエージェント、およびワークフロー実行内のすべてのエージェントは、次の2種類のいずれかです：

• 「Predefined agent」（事前定義エージェント）： あなたがすでに作成し、multiagentブロックに列挙したエージェントです。モデル、システムプロンプト、ツール、MCPサーバー、スキルといった独自の設定を使用します。
• 「Inline agent」（インラインエージェント）： 保存されていないエージェントです。セッションが実行するエージェント、またはワークフローが、作業を割り当てる際に定義します。そのエージェントのモデル、ツール、MCPサーバー、スキルを使用します。

どちらの種類も subagents と workflows の両方で機能します：

subagents.predefined_agents と workflows.predefined_agents は別々の2つのリストです。一方のリストにあるエージェントが、もう一方に追加されることはありません。どちらのリストもデフォルトでは空です。いずれのリストのエントリも、次のいずれかの形式を取ります：

• {"type": "agent", "id": agent.id} は、以前に作成した agent をIDで参照します。version が指定されていない場合、参照は、それを列挙するエージェントが作成された時点、または更新でリストが送信された時点でのエージェントの最新バージョンに固定されます。
• {"type": "agent", "id": agent.id, "version": agent.version} は、特定のエージェントバージョンを固定します。
• 文字列としての agent.id 単体は、{"type": "agent", "id": agent.id} の省略形です。
• {"type": "self"} はエージェント自身を列挙し、そのコピーが作業を行えるようにします。セッションがエージェント設定のオーバーライド付きで作成された場合、それらのオーバーライドはこれらのコピーにも適用されます。IDで参照されるエントリは影響を受けません。

これらのエントリ、およびそれらが指定するエージェントに関するルールは、両方のリストに適用されます。サブエージェントを列挙するを参照してください。

インラインエージェントは、どちらの設定でもデフォルトでオンです。列挙したエージェントのみを許可するには、subagents、workflows、またはその両方で inline_agents を {"type": "disabled"} に設定します。インラインエージェントをオフにした設定では、その predefined_agents リストに少なくとも1つのエージェントが必要です。リストが空の場合、リクエストは400エラーで失敗します。更新時には、サーバーは更新後の状態の設定をチェックします。

次のエージェントは、列挙したエージェントのみを許可します。1つのエージェントと自身のコピーに委任でき、ワークフローは別のエージェントのバージョン2を使用できます：

{
  "multiagent": {
    "type": "multiagent_20261001",
    "subagents": {
      "type": "enabled",
      "inline_agents": { "type": "disabled" },
      "predefined_agents": ["agent_01J8XkN5uT3vHpLqRfWdY2", { "type": "self" }]
    },
    "workflows": {
      "type": "enabled",
      "inline_agents": { "type": "disabled" },
      "predefined_agents": [
        { "type": "agent", "id": "agent_01Lm4cV8yQ2tNs7XbKdR5h", "version": 2 }
      ]
    }
  }
}

サブエージェントに委任する

何を委任するか

マルチエージェントの連携は、さまざまな領域にまたがる作業を必要とする複雑なタスクや、範囲が明確に定められた複数のタスクが全体の目標に貢献するタスクに最適です。

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

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

仕組み

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

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

サブエージェントがどの設定を使用するかは、それが事前定義エージェントかインラインエージェントかによって異なります。セッションレベルのエージェント設定のオーバーライドは、セッションが実行するエージェントとその self コピーに適用されます。各エージェントは独自の会話履歴を保持します。

サブエージェントを列挙する

エージェントを定義する際に、multiagentブロック内のsubagentsのpredefined_agentsリストを設定して、委任先のエージェントを列挙します：

ant apply engineering-lead.md reviewer.md test-writer.md

---
name: Engineering Lead
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: multiagent_20261001
  subagents:
    type: enabled
    predefined_agents: # ant apply replaces each path with {type: agent, id, version}
      - ./reviewer.md
      - ./test-writer.md
---

You coordinate engineering work. Delegate code review to the reviewer agent
and test writing to the test agent.

---
name: reviewer
model: claude-haiku-5-5
---

You are a code reviewer.

---
name: test-writer
model: claude-haiku-5-5
---

You write unit tests.

インラインエージェントをオフにしない限り、エージェントはインラインエージェントにも委任できます。その設定、およびsubagentsのpredefined_agentsリストのエントリがとる形式については、事前定義エージェントとインラインエージェントを参照してください。

"advisor": {"type": "enabled", "model": "<model id>"}は、セッションのプライマリスレッドに、ターンの途中で相談できるアドバイザーを付与します。アドバイザーはmultiagentブロック内の設定であり、このリストのエントリではありません。セッションにアドバイザーを与えるを参照してください。

このタイプでは動的ワークフローもデフォルトで有効になっているため、このエージェントは多数のエージェントをバックグラウンドで実行する大規模な作業を計画できます。これをオフにする場合、またはワークフローが使用できるエージェントを列挙する場合は、動的ワークフローを有効にするを参照してください。

次のルールは、subagentsのpredefined_agentsリストに列挙したエージェント、およびworkflowsのpredefined_agentsリストに列挙したエージェントにも適用されます：

• 固定： subagentsのpredefined_agentsリストを含むエージェントの設定は、エージェントの作成時または更新時にスナップショットされます。参照されるエージェントはその時点で解決されたバージョンに固定されたままとなり、その後の定義の更新は反映されません。リストを送信しない更新では、すでに固定されているバージョンが維持されます。参照されるエージェントの新しいバージョンに委任するには、subagentsのpredefined_agentsリストがそのバージョンを参照するようにエージェントを更新してください。
• 1階層： エージェントは1階層のエージェントにのみ委任できます。multiagentが設定されている別のエージェントを参照すると、作成または更新リクエストは400バリデーションエラーで失敗します。
• 最大20エージェント： subagentsのpredefined_agentsリストには、最大20個の一意のエージェントを列挙できます。この制限はリストごとです。workflowsのpredefined_agentsリストにも最大20個を列挙できます。エージェントは、セッションのスレッド制限の範囲内で、各サブエージェントの複数のコピーを呼び出せます。
• 推論地域： エージェントと、subagentsまたはworkflowsのpredefined_agentsリストに列挙したすべてのエージェントは、同じ推論地域（エージェント定義のmodel内のinference_geo）を固定するか、いずれも固定しないかのどちらかである必要があります。いずれかのリストで不一致があると、400バリデーションエラーで拒否されます。このチェックは、エージェントの保存時と、セッション作成時のオーバーライドがいずれかの固定を変更した時の両方で実行されます。

セッションを作成する

エージェントを参照するセッションを作成します。エージェントは必要に応じて、subagentsのpredefined_agentsリストに列挙したエージェントに委任します。オフにしない限り、インラインエージェントにも委任できます。

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

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

MCPサーバーはエージェントスコープです。各エージェント定義は独自のサーバーとツールを宣言します。インラインエージェントにはエージェント定義がないため、セッションが実行するエージェントのMCPサーバーとツールを使用します。ボールトの認証情報はセッションスコープです。セッション作成時に渡されたvault_idsはすべてのスレッドに適用されます。統合においては次の2つの点に注意してください：

• MCPサーバーを認証するには、すべてのエージェントで使用されるすべてのMCPサーバーのボールト認証情報を含めてください。
• エージェントのアクセスを制限するには、そのエージェント定義で必要なサーバーのみを宣言してください。インラインエージェントはこの方法では制限できません。列挙したエージェントのみを許可するには、subagentsとworkflowsの両方でinline_agentsを無効にし、それぞれに少なくとも1つのエージェントを列挙してください。事前定義エージェントとインラインエージェントを参照してください。

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

limitedの環境では、エージェント、またはsubagentsもしくはworkflowsのpredefined_agentsリストに列挙したエージェントが、ホストがallowed_hostsに含まれていないMCPサーバーを宣言している場合、セッションの作成は400エラーで失敗します。環境のネットワーク設定でallow_mcp_serversをtrueに設定すると、このチェックはオフになります。

GitHub MCPサーバーを宣言するリサーチャーと、リサーチャーに委任するエージェントを作成します：

ant apply lead.md researcher.md

---
name: lead
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: multiagent_20261001
  subagents:
    type: enabled
    predefined_agents: # ant apply replaces each path with {type: agent, id, version}
      - ./researcher.md
---

---
name: researcher
model: claude-haiku-5-5
mcp_servers:
  - type: url
    name: github
    url: https://api.githubcopilot.com/mcp/
tools:
  - type: mcp_toolset
    mcp_server_name: github
---

次に、GitHubの認証情報を保持するボールトを指定してセッションを作成します：

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

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

スレッド

各エージェントのセッションスレッドには独自のイベントストリームがあります。スレッドの一覧表示、中断、アーカイブ、イベントの読み取り、およびスレッド間でのツール権限の処理については、セッションスレッドを参照してください。

動的ワークフロー

動的ワークフローを使用すると、エージェントは数百のドキュメントのレビューや多数のソースのクロスチェックなど、多数の部分からなる作業に取り組むことができます。エージェントは「workflow」（ワークフロー）を作成します。これは、多数のエージェントをフェーズごとに実行し、それらが返す内容を統合するプログラムです。サーバーはそれを「workflow run」（ワークフロー実行）としてバックグラウンドで実行し、その間エージェントは作業を続けるか、ターンを終了します。動的ワークフローは、エージェントのmultiagentブロック内のworkflows設定でオンまたはオフにします。実行内のエージェントは同時に作業できるため、1つのエージェントが各部分を順番に処理する場合よりも、長時間のタスクを早く完了できます。

• 実行の開始方法： user.message で作業内容を説明します。それをもとに、エージェントが実行を開始するかどうか、いつ開始するかを判断するため、追加のAPI呼び出しは不要です。代わりに、user.message またはエージェントのシステムプロンプトで実行をいつ使用すべきかを説明することで、エージェントの判断に影響を与えます。（権限ポリシーは、実行の開始ではなく、実行内のエージェントが呼び出すツールに適用されます。）
• 使用するエージェント： ワークフローが定義するインラインエージェント、workflowsのpredefined_agentsリストに列挙した事前定義エージェント、またはその両方です。何も列挙しない場合、ワークフローがすべてのエージェントを定義します。インラインエージェントは、セッションが実行するエージェントのモデルを使用します。実行内の一部のエージェントに別のモデルを使用させるには、それらをエージェントとして作成し、workflowsのpredefined_agentsリストに列挙してください。
• 追跡方法： 実行イベントはセッションのイベントストリームに届き、実行内の各エージェントは、一覧表示、読み取り、ストリーミングが可能なセッションスレッドで作業します。イベント、中断、制限、および実行のスレッドに表示される内容については、ワークフロー実行を参照してください。

動的ワークフローを有効にする

エージェントを定義する際に、multiagent.type を "multiagent_20261001" に設定し、workflows を有効にします。このタイプでは、動的ワークフローと委任（subagents）の両方がデフォルトで有効になっています。動的ワークフローのみを使用する場合は、"subagents": {"type": "disabled"} を追加します。

既存のエージェントの multiagent.type を変更する前に、エージェントをこのタイプに移行する方法を参照してください。

ant apply contract-reviewer.md

---
name: Contract Reviewer
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: multiagent_20261001
  workflows:
    type: enabled
---

You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.

すでに作成済みのエージェントをワークフローで使用できるようにするには、それらを workflows.predefined_agents に列挙します。subagents と advisor の設定も同じ multiagent ブロックに記述します。サブエージェントを列挙するには、サブエージェントに委任するを参照してください。アドバイザーを設定するには、セッションにアドバイザーを与えるを参照してください。次のエージェントは、作成済みのエージェント1つをワークフローで使用できるようにし、2つのサブエージェントを列挙し、アドバイザーを持っています：

{
  "multiagent": {
    "type": "multiagent_20261001",
    "workflows": {
      "type": "enabled",
      "predefined_agents": [{ "type": "agent", "id": "agent_01Lm4cV8yQ2tNs7XbKdR5h" }]
    },
    "subagents": {
      "type": "enabled",
      "predefined_agents": [
        { "type": "agent", "id": "agent_01J8XkN5uT3vHpLqRfWdY2" },
        { "type": "agent", "id": "agent_01HqR2k7vXbZ9mNpL3wYcT" }
      ]
    },
    "advisor": { "type": "enabled", "model": "claude-opus-5-5" }
  }
}

各設定はそれぞれ個別に有効または無効にできます：

各リストに何を記述するか、および列挙したエージェントのみを許可する方法については、事前定義エージェントとインラインエージェントを参照してください。

次の点に留意してください：

• 更新： multiagent_20261001 タイプを維持する更新では、送信した内容のみが変更されます：
  • 省略した設定やフィールドは、保存されている値を保持します。
  • null として送信した設定やフィールドはデフォルト値になり、その内部のすべても、保存されていた内容にかかわらずデフォルト値になります。
  • 送信した predefined_agents リストは、保存されているリストを置き換えます。
  • 異なる type で送信した設定は保存されている設定を置き換え、その中で省略したフィールドはデフォルト値になります。
  • 送信するすべてのオブジェクトには type が必要で、有効な advisor には model が必要です。
• 無効化： workflows を {"type": "disabled"} に設定します。更新で再び有効にするまで無効のままです。デフォルトが有効であるため、null を送信すると有効になります。subagents についても同様です。
• 既存のセッション： セッションは作成時に設定をコピーするため、後でエージェントを変更しても、すでに存在するセッションは変更されません。
• 列挙できるエージェント： multiagent が設定されているエージェントは、別のエージェントのサブエージェントとして、または別のエージェントの workflows の predefined_agents リストに列挙することはできません。エージェントは {"type": "self"} を使用して、どちらのリストにも自分自身を列挙できます。これは読み取り時に自身の id と version として返されます。
• ツール名： ant__ プレフィックスは予約されています。エージェントに名前が ant__ で始まるカスタムツールがすでにある場合、その名前を含まない tools を送信するまで、更新は400エラーで失敗します。エージェント、またはいずれかのリスト内のエージェントがそのようなツールを持っている場合、新しいセッションも400エラーで拒否されます。動的ワークフローを有効にするのと同じ更新で、そのツールの名前を変更するか削除してください。カスタムツールを参照してください。
• 予算： 実行を含むセッションの支出に上限を設けるには、セッションの作成時にセッション予算を設定します。既存のセッションに予算を追加することはできません。セッションが予算に達すると実行は一時停止し、予算によって一時停止した実行は、予算を引き上げるか削除すると再開します。ただし、中断によっても一時停止している場合は除きます。コストと予算を参照してください。

実行を使用するタイミングをエージェントに伝える

動的ワークフローを有効にすると、エージェントはワークフロー実行を開始できるようになります。実行を開始するタイミングはエージェントが判断します。その判断を導くには、次のような指示をエージェントのシステムプロンプトに追加します。動的ワークフローを有効にするの契約書レビューエージェントは、次のシステムプロンプトを使用しています：

You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.

これを応用するには、エージェントのドメインにおいてワークフロー実行が必要なタスクと、エージェント自身が行うべき小さなタスクを明示します。次の例のように、実行での作業の進め方を指示することもできます：

• 作業の分割方法：「実行では、契約書ごとに1つのエージェントを使用してください。次に、2つ目のエージェントに、最初のエージェントが何かを見つけた契約書だけでなくすべての契約書をレビューさせ、最初のエージェントが見落としたものを探させてください。レビューに合格しなかったものはやり直し、再度レビューします。」
• エージェントが失敗した場合の対処：「1つのエージェントの失敗によって実行全体を失敗させてはいけません。エージェントが契約書を読み取れなかった場合は、その契約書を対象外として列挙してください。実行が終了したら、どの契約書が対象外だったかを教えてください。」
• 時間制限：「実行に1時間の時間制限を設けてください。」
• まず計画する：「実行を開始する前に、そのフェーズと各フェーズで実行するエージェントの数を説明してください。その後、私の承認を待ってください。」実行の開始前に承認ステップはないため、これを強制する仕組みはありません。

実行内のすべてのエージェントがトークンを使用するため、実行は必要なタスクに限定してください。

その後、他のエージェントと同様に、そのエージェントでセッションを作成し、user.message で作業内容を説明します。そのメッセージでワークフロー実行を依頼することもできます。

実行のイベント、実行が開いている状態でのセッションの中断、実行が開いている間に変わること、および予算と制限については、ワークフロー実行を参照してください。

セッションにアドバイザーを与える

エージェントの multiagent ブロックで advisor 設定を有効にすると、セッションのプライマリスレッドにアドバイザーが付きます。アドバイザーとは、アプローチの計画、行き詰まりの打開、完了前の作業レビューなど、戦略的なガイダンスを得るためにターンの途中で相談できるモデルです。この設定はデフォルトで無効です。有効にするには、advisor を {"type": "enabled", "model": "..."} に設定します。これには type と model のちょうど2つのフィールドがあります：

ant apply backend-engineer.md

---
name: Backend engineer
model: claude-sonnet-5
multiagent:
  type: multiagent_20261001
  advisor:
    type: enabled
    model: claude-opus-5-5
---

You implement backend features end to end. Consult the advisor before major backend design decisions.

この例では advisor のみを設定しています。他の2つの設定である subagents と workflows はデフォルトのままなので両方とも有効であり、エージェントはインラインエージェントへの委任やワークフロー実行の開始も行えます。アドバイザーに相談しつつすべての作業を自分で行うエージェントにするには、両方を {"type": "disabled"} に設定します。

アドバイザーを subagents または workflows の predefined_agents リストに列挙することはできません。有効な advisor は anthropic.advisor という名前を予約します。有効になっている間は、どちらのリストにも文字どおり anthropic.advisor という名前のエージェントを含めることはできず、そのリクエストは400バリデーションエラーで拒否されます。

アドバイザーモデルは最低限の能力基準を満たす必要があり、エージェント自身のモデルはアドバイザーより高い能力を持っていてはいけません。同等の能力を持つモデル同士は組み合わせることができます。無効な組み合わせは、エージェントの保存時に400バリデーションエラーで拒否され、セッションの作成時にも再度拒否されます。組み合わせは各相談の開始時にもチェックされます。もはや有効でない場合、その相談は失敗しますが、セッションは継続します。有効な組み合わせは、アドバイザーツールのモデル互換性の表に従います。

アドバイザーはMessages APIのサーバーツールとしても利用できます。Managed Agentsでは設定と配信の方法が異なります。advisor 設定には max_uses、max_tokens、caching フィールドがなく、アドバイスは advisor_tool_result ブロックではなくスレッドイベントを通じて届きます。

相談の仕組み

各相談は、プラットフォームが生成する anthropic.advisor という名前のスレッドとして実行され、相談が完了するとそのスレッドは自ら終了します。アドバイスは agent.thread_message_received イベントとしてプライマリスレッドに配信されます。相談では、予約名 anthropic.advisor で識別される標準のスレッドイベントが発行されます（スレッドのライフサイクルイベントではこれを agent_name として、アドバイスの配信では from_agent_name として保持します）。通常は次の順序で発行されます：

1. session.thread_created
2. session.thread_status_running
3. agent.thread_message_received（アドバイス）
4. session.thread_status_idle（stop_reason: end_turn）
5. session.thread_status_terminated

相談の入力はエージェントが送信するのではなくプラットフォームによって構成されるため、相談に対して agent.tool_use イベントは発行されず、セッションのイベントストリームに agent.thread_message_sent イベントも現れません。アドバイザースレッド自身のイベントを一覧表示すると、アドバイスはそこにも agent.thread_message_sent イベントとして現れます。アドバイスの配信（イベント3）がアドバイザースレッドのアイドルイベントや終了イベントより前に届くことは保証されていないため、それらをアドバイスがすでに配信されたことのシグナルとして扱わないでください。

クライアントがアドバイスを読めるかどうかは、アドバイザーモデルのポリシーによります。これはMessages APIのアドバイザーツールにおける結果のバリアントの区別を反映しています。そちらでプレーンテキストの結果を返すアドバイザーモデルは、ここでも読み取り可能なテキストを配信します。秘匿化された結果を返すモデルは、すべてのクライアント側で [{"type": "redacted"}] プレースホルダーを配信しますが、エージェントはサーバー側で完全なアドバイスを読み取ります。前述の例では、利用可能な最新のOpusモデルをアドバイザーとして使用しています。Claude Opus 5.5は秘匿化された結果を返すため、クライアントにはプレースホルダーのみが表示されます。イベントストリームでアドバイスを読むには、Claude Opus 4.8など、プレーンテキストを返すアドバイザーを使用してください。モデルのポリシーはAPIの変更なしに変わる可能性があるため、text ブロックと redacted ブロックの両方を処理してください。一部のエージェントモデルは、秘匿化された結果を返すアドバイザーとのみ組み合わせることができます。アドバイザーツールの互換性の表を参照してください。アドバイザーの思考が表示されることはありません。クライアントが自ら redacted ブロックを送信することはできず、それを含むイベントは400バリデーションエラーで拒否されます。

失敗または中断された相談によってエージェントのターンが失敗することはありません。エージェントは、相談が失敗したという汎用的な通知の後に処理を続行します。相談中にセッションレベルの user.interrupt を送信すると、アドバイスが配信されないままアドバイザースレッドが終了します。アドバイザースレッドの session_thread_id を指定した user.interrupt は、その相談のみを中止します。

アドバイザースレッド

アドバイザーはサブエージェントではありません。エージェントの list_agents ツールには表示されず、サブエージェントにフォローアップメッセージを送信する send_to_agent でも到達できません。アドバイザーに相談できるのはセッションのプライマリスレッドのみで、サブエージェントは相談できません。

アドバイザースレッドは、25個の子スレッドの制限の対象外です。アドバイザースレッドはセッションのスレッド一覧に表示されます。その agent はアドバイザー形式の {"type": "advisor", "model": ...} で、設定したモデルが入り、parent_thread_id はプライマリスレッドです。

アドバイザー側のプロンプトキャッシングは自動で行われ、設定は不要です。相談はアドバイザーモデルの料金で課金され、そのトークンはアドバイザースレッドの使用量とセッションの使用量合計に表示されます。また、アドバイザーモデルの定価でセッション予算にも計上されます。各相談ではそれまでのプライマリスレッドの会話がアドバイザーに送信されるため、長いセッションの後半での相談ほど多くの入力トークンを使用します。

アドバイザーを削除する

アドバイザーを削除するには、advisor を {"type": "disabled"} に設定してエージェントを更新します。すでに multiagent_20261001 タイプを持つエージェントでは、更新で省略した設定は保存されている値を保持するため、subagents や workflows を再度送信する必要はありません。同じ理由で、advisor を省略した更新ではアドバイザーが保持されます。既存のエージェントの multiagent.type を変更する前に、エージェントをこのタイプに移行する方法を参照してください。

coordinator タイプからの移行

multiagent_20261001 と同様に、coordinator タイプでは、エージェントは列挙したサブエージェントに委任したり、アドバイザーモデルに相談したりできます。coordinator タイプでは、エージェントはワークフロー実行を開始したり、サブエージェントを自ら定義したりすることはできません。APIは両方のタイプを受け付けます。

エージェントを multiagent_20261001 に移行するには、そのタイプの multiagent ブロックでエージェントを更新します：

1. type を "multiagent_20261001" に設定します。
2. エージェントが呼び出せるエージェントを subagents.predefined_agents に列挙します。エントリは現在の形式のままです。
3. エージェントにアドバイザーがある場合は、アドバイザーのモデルを指定して advisor を {"type": "enabled", "model": "..."} に設定します。
4. ブロック全体を1回の更新で送信します。

たとえば、次のブロックはエージェントに2つのサブエージェントとアドバイザーを付与します：

{
  "multiagent": {
    "type": "multiagent_20261001",
    "subagents": {
      "type": "enabled",
      "predefined_agents": [
        { "type": "agent", "id": "agent_01J8XkN5uT3vHpLqRfWdY2" },
        { "type": "agent", "id": "agent_01HqR2k7vXbZ9mNpL3wYcT" }
      ]
    },
    "advisor": { "type": "enabled", "model": "claude-opus-5-5" }
  }
}

このブロックでは workflows と subagents.inline_agents を省略しているため、両方ともデフォルト値になり有効になります。移行したエージェントは、ワークフロー実行の開始やサブエージェントの自己定義も行えます。いずれかを無効のままにするには、同じ更新でそれを {"type": "disabled"} に設定します。動的ワークフローを有効にするおよび事前定義エージェントとインラインエージェントを参照してください。

エージェントにアドバイザーがあってサブエージェントがない場合は、委任を無効のままにするために subagents を {"type": "disabled"} に設定します。subagents.inline_agents を無効にし、エージェントを1つも列挙しないリクエストは400エラーで失敗します。

更新は multiagent ブロック全体を置き換えるため、例のようにエージェントのリストとアドバイザーを再度送信してください。省略したものはデフォルト値になります：

• subagents.predefined_agents： リストが空になるため、エージェントは列挙していたサブエージェントを失います。
• advisor： アドバイザーが無効になります。

エージェントが multiagent_20261001 タイプになった後は、以降の更新で省略した設定は保存されている値を保持します。

更新によって、すでに存在するセッションは変更されません。新しいブロックを使用するには、更新後にセッションを作成してください。