Claude Media
Managed Agentsのpredefined_agentsとinline — 呼べる相手を絞る設定
AnthropicAgent SDK解説

Managed Agentsのpredefined_agentsとinline — 呼べる相手を絞る設定

Managed Agentsのmultiagent_20261001で、subagentsとworkflowsが呼べるエージェントを絞る設定と、更新時のバージョン固定の落とし穴を解説します。

読了目安 約11分

Managed Agentsのmultiagent_20261001では、エージェントが呼べる相手をpredefined_agentsとinline_agentsの2つの設定で決めます。何も書かないと、エージェント自身が即席で作る「inline」の相手が呼び放題です。

呼べる相手を自分で作ったエージェントだけに絞るには、inline_agentsを無効にして、predefined_agentsに相手を並べます。ただし、subagentsとworkflowsは別々のリストで、片方に書いてももう片方には届きません。

この記事では、2種類のエージェントの違い、絞り込みの書き方、更新時にハマる固定の仕組みを順に見ます。

predefinedとinlineは何が違うか

multiagentブロックから呼ばれるエージェントは、必ず次のどちらかです。

  • predefinedエージェント: 事前に作成済みで、multiagentブロックにリストしたエージェント。自分のモデル・システムプロンプト・ツール・MCPサーバー・スキルで動く
  • inlineエージェント: 保存されないエージェント。セッションを動かすエージェントか、ワークフローが委譲のときに定義する。モデル・ツール・MCPサーバー・スキルは、セッションを動かすエージェントのものを使う

どちらもsubagentsとworkflowsの両方で使えます。設定の置き場所が変わるだけです。

種類subagentsworkflows
predefinedsubagentssubagents.predefined_agentsに並べた相手へ委譲できるworkflowsworkflows.predefined_agentsに並べた相手をワークフローが使える
inlinesubagents委譲時にエージェントが定義できる。subagents.inline_agentsで有効・無効を切り替えるworkflowsワークフローが相手ごとにシステムプロンプトを書いて定義できる。workflows.inline_agentsで切り替える

multiagent_20261001を指定しただけのブロックは、subagentsもworkflowsも有効で、どちらもinline_agentsが有効になります。predefined_agentsはどちらも空です。つまり初期状態では、リストした相手がゼロで、inlineだけが動く構成です。

inlineは何を引き継ぐか

inlineエージェントにはエージェント定義がありません。そのため、セッションを動かすエージェントのモデル・ツール・MCPサーバー・スキルをそのまま使います。ワークフローの場合も、inlineエージェントはセッションを動かすエージェントのモデルで動きます。

別のモデルで動かしたい相手がいるなら、エージェントとして作成し、workflows.predefined_agentsにリストします。安いモデルを調査役にして、高性能なモデルをまとめ役にする、といった構成は、predefinedにしないと作れません。

呼べる相手を絞る設定の書き方

リストの1要素は、4つの形のどれかで書きます。

書き方意味
{"type": "agent", "id": "<agent_id>"}意味作成済みエージェントをIDで参照する。versionを省くと、リストを送った時点の最新バージョンに固定される
{"type": "agent", "id": "<agent_id>", "version": 2}意味バージョンを指定して固定する
"<agent_id>"意味1行目の短縮形
{"type": "self"}意味自分自身をリストする。自分のコピーに作業させられる

selfを使うと、セッション作成時の設定上書き(エージェント設定のオーバーライド)があるとき、コピーにも同じ上書きが効きます。IDで参照した相手には効きません。

許可した相手だけに絞る例が次のとおりです。公式の例に沿った形です。

{
  "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つと自分のコピー」、ワークフローが使えるのが「別のエージェントのバージョン2」です。inlineは両方で無効なので、それ以外の相手は作れません。

inlineを無効にする条件

inline_agentsを{"type": "disabled"}にした設定には、predefined_agentsに1件以上の相手が必要です。空のままだと400エラーで拒否されます。更新のときは、更新後の設定の状態が検査されます。

落とし穴

inlineを切っただけで保存すると400になる

subagentsのinlineだけを無効にして、リストを空のまま送ると失敗します。無効にする設定ごとに、少なくとも1件をリストします。coordinatorタイプからの移行で、サブエージェントなしにしたい場合は、subagents自体を{"type": "disabled"}にします。

subagentsとworkflowsは別のリスト

subagents.predefined_agentsとworkflows.predefined_agentsは、別々の2本のリストです。片方に入れたエージェントは、もう片方に自動では追加されません。どちらも初期値は空です。

リストごとの上限は、どちらも20エージェントです。合計で20ではありません。同じエージェントのコピーは、セッションのスレッド上限の範囲で複数回呼べます。

実際の運用では、次のようにズレが出ます。

  • レビュー担当をsubagentsにだけ入れた場合、ワークフローの中ではレビュー担当を使えない。ワークフローがinlineを定義して代役を立てるか、inlineを無効にしていれば使えない
  • ワークフロー用の安いモデルの調査役をworkflowsにだけ入れた場合、通常の委譲では呼べない

「全部の経路で同じ顔ぶれにしたい」ときは、両方のリストに同じエージェントを書きます。

どちらを絞るか

subagentsは、エージェントが自分で結果を読んで次の手を決める委譲です。サブエージェントのスレッドは、アーカイブするまで残ります。workflowsは、プログラムが多数のエージェントを動かして結果をまとめる経路で、実行中のスレッドへ追加メッセージは送れず、実行の終わりにサーバーがアーカイブします。

絞る基準は、どの経路に何をさせたいかです。コスト面の考え方はManaged Agentsのオーケストレーターでコストが下がる2条件でも扱っています。ワークフローは動かす本数が多いぶんトークンを使うため、セッション予算を併せて設定します。

更新で起きるバージョン固定の落とし穴

最も見落としやすいのが、参照先のエージェントを更新しても、呼び出す側には反映されない点です。

エージェントの設定は、作成時または更新時にスナップショットされます。multiagentブロックで参照した相手は、そのとき解決されたバージョンに固定されたままで、後からその相手の定義を更新しても取り込まれません。

具体的には、次の流れです。

手順

参照先を更新しても呼び出し側が古いままになる流れ

  1. 1

    リーダーを作成する

    versionを省いた形で、レビュー担当をsubagents.predefined_agentsに入れて作成する。この時点の最新バージョン(たとえば1)に固定される。

  2. 2

    レビュー担当を更新する

    レビュー担当のシステムプロンプトを直して、バージョン2にする。

  3. 3

    リーダーは古いまま

    リーダーの定義は、更新を送っていないのでバージョン1の参照を保持する。新しいセッションを作っても、委譲先はバージョン1のレビュー担当になる。

直すには、リーダーを更新して、predefined_agentsのリストを送り直します。公式は、新しいバージョンへ委譲するには「そのバージョンを参照するようにリストを含めて更新する」としています。

更新の挙動をまとめると

multiagent_20261001のまま更新するとき、送ったものだけが変わります。

更新で送るもの結果
設定やフィールドを省く結果保存済みの値のまま
nullを送る結果その設定と中身がすべて既定値に戻る
predefined_agentsのリスト結果保存済みのリストを置き換える
別のtypeを持つ設定結果保存済みの設定が置き換わり、省いたフィールドは既定値になる

リストを送らない更新は、固定済みのバージョンを維持します。つまり、リーダーの別の項目(システムプロンプトなど)だけを直す更新では、委譲先のバージョンは進みません。

nullの扱いにも注意が必要です。workflowsを{"type": "disabled"}にした後にnullを送ると、既定値の有効に戻ります。subagentsも同じです。無効にしたつもりの機能が、nullで再び有効になります。

既存のセッションには効かない

セッションは作成時に設定をコピーします。リーダーのリストを更新しても、すでにあるセッションの委譲先は変わりません。新しい設定を使うには、更新の後でセッションを作り直します。

絞り込みが効かない・拒否されるケース

リストに入れる相手には、いくつか制約があります。

  • 1段まで: multiagentを設定済みのエージェントは、別のエージェントのsubagentsにも、workflows.predefined_agentsにもリストできない。作成・更新が400で失敗する
  • 推論ジオグラフィ: 呼び出す側と、リストした全員が同じinference_geoを固定するか、全員が固定しないかのどちらか。食い違いは400で拒否される。セッション作成時の上書きでも検査される
  • アドバイザー: アドバイザーはリストの要素ではなくadvisorという別の設定。有効な間は、anthropic.advisorという名前のエージェントをどちらのリストにも入れられない。アドバイザーの設計はManaged Agentsのマルチエージェントにアドバイザーをつけるにある
  • 予約済みのツール名: ant__で始まる名前のカスタムツールがあると、更新が400で失敗する。セッションも、呼び出す側かリスト内のエージェントにそのツールがあれば拒否される

MCPとネットワークの絡み方

MCPサーバーは、エージェント定義ごとの宣言です。inlineエージェントには定義がないので、呼び出す側のMCPサーバーとツールをそのまま使います。公式は、inlineエージェントについてはアクセスを個別に絞れないとしています。

アクセスを絞りたいなら、MCPサーバーを最小限だけ宣言した専用エージェントを作り、inline_agentsをsubagentsとworkflowsの両方で無効にして、各リストに1件以上並べます。

環境のネットワークがlimitedのとき、呼び出す側かリスト内のエージェントがallowed_hostsにないホストのMCPサーバーを宣言していると、セッション作成が400で失敗します。環境側でallow_mcp_serversをtrueにすると、この検査は外れます。

coordinatorからの移行で消えるもの

旧来のcoordinatorタイプでは、委譲先をagents配列に書いていました。構成の基本はManaged Agentsでマルチエージェントを編成する方法で説明しています。coordinatorタイプのエージェントは、ワークフローの実行も、サブエージェントの自前定義もできません。multiagent_20261001へ移すと、この2つが既定で有効になります。

移行の更新は、multiagentブロック全体を1回で送ります。

  1. typeを"multiagent_20261001"にする
  2. 呼べる相手をsubagents.predefined_agentsに並べる。要素の形はそのまま使える
  3. アドバイザーがあればadvisorを{"type": "enabled", "model": "..."}で指定する

ブロックを置き換える更新なので、リストとアドバイザーを送り直さないと、subagents.predefined_agentsは空に、advisorは無効になります。移行した直後はinlineもワークフローも有効なので、従来どおり「リストした相手だけ」に保ちたい場合は、同じ更新でinline_agentsとworkflowsを無効にします。

その後は、multiagent_20261001のまま更新するかぎり、省いた設定は保存済みの値を保持します。

設計の使い分けの早見表

目的設定
初期状態のまま、何でも呼ばせる設定multiagentにtypeだけを書く
委譲先を自作の専門エージェントに限る設定subagents.inline_agentsを無効にしてpredefined_agentsに並べる
ワークフローの一部だけ別モデルで動かす設定そのエージェントを作成してworkflows.predefined_agentsに入れる
ワークフローも自作の相手に限る設定workflows.inline_agentsも無効にして1件以上並べる
参照先の更新を取り込む設定呼び出し側を更新してpredefined_agentsを送り直す

まとめ

predefined_agentsは「呼べる相手の名簿」、inline_agentsは「名簿にない相手をその場で作る許可」です。絞り込みは、この許可を切って名簿を埋める作業になります。

名簿はsubagentsとworkflowsで別々に持ち、参照した相手はリストを送った時点のバージョンに固定されます。相手を更新した日は、呼び出し側の更新とセッションの作り直しまでが1セットです。

この記事を共有:XはてブLinkedIn

関連する記事

Anthropic をもっと見る →