allowed_callersの3パターン使い分け — プログラマティックツールコーリング

allowed_callersが決めるのは呼び出し元、3つの値だけ

プログラマティックツールコーリングは、Claudeにツール呼び出しをコードとして書かせ、コード実行のサンドボックス内でまとめて処理させる仕組みです。1件ずつモデルとの往復を挟む代わりに、複数のツール呼び出しを1つのスクリプトにまとめられるため、レイテンシとトークン消費の両方を削減できます。

この仕組みを個々のツール定義に適用するのがallowed_callersフィールドです。値は3つしかありません。

{
  "name": "query_database",
  "description": "Execute a SQL query against the database",
  "input_schema": { "...": "..." },
  "allowed_callers": ["code_execution_20260120"]
}

• ["direct"] — 省略時の既定値。Claudeがそのツールを直接呼ぶ、従来どおりのツール呼び出し
• ["code_execution_20260120"] — コード実行環境の中からだけ呼べる
• ["direct", "code_execution_20260120"] — どちらからでも呼べる

利用にはコード実行ツールが必須で、ツールバージョンはcode_execution_20260120以降が要求されます。code_execution_20260120とcode_execution_20260521はどちらも受け付けられ、相互に互換です(どちらのバージョンでリクエストしても、レスポンス側のcallerは常にcode_execution_20260120と表示されます)。

3パターンの使い分け早見表

ドキュメントのTipは、ツールごとに["direct"]か["code_execution_20260120"]のどちらか一方を選ぶ方が、Claudeへのガイダンスが明確になると説明しています。両方を許したツールは、直接呼ぶのかコードから呼ぶのかの手がかりが薄くなります。

判断の具体例として、20人分の従業員の経費が予算内かをチェックするケースを考えます。従来のツール呼び出しでは、1人ずつ結果をコンテキストへ積みながら20往復のモデル呼び出しが発生し、数千件の経費明細行がそのままコンテキストに流れ込みます。経費照会ツールにallowed_callers: ["code_execution_20260120"]を付けておけば、Claudeは20人分の照会をまとめて1つのスクリプトとして書き、予算超過者だけを絞り込んだ結果をコンテキストに返せます。モデルが読む量は数百キロバイトから数行にまで縮みます。

コードから見たツールは、文字列を返す非同期関数

allowed_callersにコード実行を含めたツールは、Claudeが書くPythonコードの中で非同期関数として見えます。関数は引数を1つのdictで受け取り、あなたが返したtool_resultのテキストを文字列として返します。Claudeのコードはトップレベルのawaitで呼び、必要なら自分でパースします。複数の呼び出しはasyncio.gatherで並列にも走らせられます。

rows = json.loads(await query_database({"sql": "<sql>"}))

返り値が文字列なので、ツール側で決めるべきことが1つあります。ツールのdescriptionに出力形式を具体的に書いておくことです。JSONを返すと書いてあれば、Claudeはコード内でjson.loadsして加工します。書式が曖昧だと、結果をうまくパースできずに失敗する原因になります。返すデータは機械が読める形式にして、必要な項目だけに絞ると処理の負荷も下がります。

1回のコード実行で、APIはどこで止まるか

コード実行の途中でツール関数が呼ばれるたびに、APIはいったん止まってあなたの側に処理を返します。この往復がプログラマティック呼び出しの実体です。

直接呼び出しとサーバーツールが同じターンに混ざったときのstop_reasonの見分け方は、tool_useとpause_turnの違いにまとめています。

tool_choiceと組み合わせると400エラーになる条件

allowed_callersから"direct"を外したツールを、tool_choiceで名指しして強制しようとすると、invalid_request_errorのHTTP 400が返ります。

{
  "name": "query_database",
  "allowed_callers": ["code_execution_20260120"]
}

上のようなツール定義に対して"tool_choice": {"type": "tool", "name": "query_database"}を指定すると失敗します。直す方法は2つです。そのツールのallowed_callersに"direct"を足すか、tool_choiceからそのツールを外してClaudeにコード経由での呼び出しを任せるかのどちらかです。

これとは別に、tool_choiceで特定のツールのプログラマティック呼び出しそのものを強制することはできません。tool_choiceはあくまで「どのツールを使うか」を指定する仕組みで、「コード実行経由で呼ぶか、直接呼ぶか」までは制御できません。

コード実行を許可できないツールと機能の組み合わせ

tool_choice以外にも、allowed_callersにコード実行を含められない条件があります。

callerフィールドで呼び出し経路を判別する

レスポンスのtool_useブロックには、必ずcallerフィールドが含まれ、実際にどちらの経路で呼ばれたかが分かります。

{
  "type": "tool_use",
  "id": "toolu_xyz789",
  "name": "query_database",
  "input": { "sql": "..." },
  "caller": {
    "type": "code_execution_20260120",
    "tool_id": "srvtoolu_abc123"
  }
}

tool_idは、その呼び出しを行ったコード実行のserver_tool_useブロックのIDです。1つのコード実行が複数のツールを呼んだとき、どのtool_useがどのコード実行に属するかをこのIDで突き合わせられます。直接呼び出しの場合はcallerが{"type": "direct"}だけになります。ログ収集や課金の内訳を追うときは、このcallerフィールドを見れば経路を機械的に判別できます。

課金の数え方も経路で違います。プログラマティック呼び出しのツール結果は、入力/出力トークンの使用量にカウントされません。カウントされるのは、コード実行が最終的に返す結果とClaudeの応答だけです。料金体系はコード実行ツールと同じです。

利用できる面を確認する — Bedrock・Google Cloudは非対応

プログラマティックツールコーリングは、Claude API・Claude Platform on AWS・Microsoft Foundry(Hosted on Anthropicデプロイ限定)で使えます。Amazon BedrockとGoogle Cloudでは利用できません。この2つでは、コード実行ツール自体が提供されていません。Microsoft Foundryも、コード実行ツールを使えるのはHosted on Anthropicデプロイに限られ、プログラマティック呼び出しの条件と重なります。

モデル側にも条件があります。対応モデルは次のとおりです。

• Fable 5.1 / Fable 5
• Mythos 5.1 / Mythos 5
• Opus 5.5 / Opus 5 / Opus 4.8 / Opus 4.7 / Opus 4.6 / Opus 4.5
• Sonnet 5.5 / Sonnet 5 / Sonnet 4.6 / Sonnet 4.5

Claude Haiku 4.5はcode_execution_20260120以降のツールバージョンをリクエストに含められますが、プログラマティックツールコーリングそのものはサポートしません。Haiku 4.5では、新しいバージョンを指定してもcode_execution_20250825と同じ動作になります。どの面・どのモデルで使うかを、実装前にこの2軸で確かめておくと、実装後に「動くはずが動かない」を防げます。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 4096,
    "messages": [{"role": "user", "content": "Query sales by region"}],
    "tools": [
      {"type": "code_execution_20260120", "name": "code_execution"},
      {
        "name": "query_database",
        "description": "Execute a SQL query. Returns rows as JSON.",
        "input_schema": {"type": "object", "properties": {"sql": {"type": "string"}}, "required": ["sql"]},
        "allowed_callers": ["code_execution_20260120"]
      }
    ]
  }'

code_execution専用にすべきツールの見分け方

["code_execution_20260120"]を付けるかどうかは、ワークロードの形で決まります。コンテナの起動とスクリプト生成という固定のオーバーヘッドを払って、ツール結果のトークンとモデルとの往復を減らす取引だからです。

Anthropicの社内評価では、ワークロードの形で効果が大きく分かれています。

迷う場合は、allowed_callersを付けた場合と付けない場合で、代表的なトラフィックの課金対象トークンを実測してから広く適用するのが、ドキュメントの勧める手順です。

ツール結果を返すときのつまずき

プログラマティック呼び出しの待ち受け中は、返し方に決まりがあります。破ると400エラーになったり、コードがタイムアウトしたりします。

最初の決まりは、結果を返すメッセージにtool_resultブロックだけを入れることです。テキストは、結果の後ろにも付けられません。

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "[{\"customer_id\": \"C1\"}]" },
    { "type": "text", "text": "What should I do next?" }
  ]
}

上のようにテキストを足した形は無効です。通常のクライアント側ツール呼び出しなら結果の後ろにテキストを置けるので、経路ごとに処理を分けていないと見落とします。また、tool_resultのcontentは文字列かtextブロックに限られ、画像やドキュメントのブロックは拒否されます。

次に、コンテナのIDです。プログラマティックなツール呼び出しの結果待ちの間は、次のリクエストにコンテナIDを付ける必要があり、付けないとAPIが拒否します。

最後に、返答の期限です。結果が約4分以内に届かないと、Claudeのコードの中でTimeoutErrorが起きます。

TimeoutError: Calling tool ['query_database'] timed out (no response after 270s).

この文言はcode_execution_tool_resultのstderrに入って返り、Claudeはたいていツールを呼び直します。アイドルのコンテナは約5分で回収され、作成から30日を超えたコンテナは再利用できません。レスポンスのexpires_atを見て、期限よりかなり前に結果を返す実装にしておきます。

なお、プログラマティック呼び出しも通常のツール呼び出しと同じレート制限の対象で、コードから呼ぶたびに1回の呼び出しとして数えられます。

code_execution_20260521ではセル単位の実行時間制限も明示される

code_execution_20260120とcode_execution_20260521はランタイムとしては同一ですが、後者はツール説明文の中でClaudeに「プログラマティックツールコーリングの中のPythonセルには90秒のウォールクロック制限がある」と伝えます。制限を超えたセルは、detection_timeoutというステータスメッセージと非ゼロのreturn_codeを伴う、通常のコード実行結果として返ります。これは、ツール呼び出し全体の実行時間が上限を超えたときに返るexecution_time_exceededエラーコードとは別物です。90秒制限はセル1つに対する制限、4分のタイムアウトは個々のプログラマティックツール呼び出しの応答待ちに対する制限、という2段構えになっています。

2025年11月のベータから何が変わったか

プログラマティックツールコーリングは、2025年11月にTool Search Tool・Tool Use Examplesと並ぶ3つのベータ機能の1つとして公開されました。当時のエンジニアリングブログの例では、ツールバージョンがcode_execution_20250825で、allowed_callersにもcaller.typeにも同じ値が入っていました。有効化にはbetas=["advanced-tool-use-2025-11-20"]のようなベータヘッダーの指定が必要でした。

現行ドキュメントは、code_execution_20250825 / 20260120 / 20260521のいずれもanthropic-betaヘッダーを必要としないと明記しています。古いベータヘッダーは、オプトインとして引き続き有効です。周辺機能の全体像はAnthropic Advanced Tool Useにまとめています。

まとめ

大量の結果を絞るツールはコード実行専用、tool_choiceで強制するツールは"direct"を残す、という分け方が出発点です。