allowed_callersの3パターン使い分け — プログラマティックツールコーリング
プログラマティックツールコーリングのallowed_callersが取る3つの値の使い分けと、tool_choiceと組み合わせたときに400エラーになる条件を示します。
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パターンの使い分け早見表
| allowed_callers | 呼び出し元 | tool_choiceで名指し | 向くツール |
|---|---|---|---|
["direct"](既定) | 呼び出し元モデルが直接 | tool_choiceで名指し可能 | 向くツール対話の中で都度結果をClaudeに見せたいツール |
["code_execution_20260120"] | 呼び出し元コード実行環境のみ | tool_choiceで名指し不可(400エラー) | 向くツール大量データのフィルタ・集計、繰り返しループの内側で呼ぶツール |
["direct", "code_execution_20260120"] | 呼び出し元どちらも可 | tool_choiceで名指し可能(directを含むため) | 向くツール基本は非推奨。両立させるとClaudeへのガイダンスが曖昧になる |
公式ドキュメントは、両方を有効にするより["direct"]か["code_execution_20260120"]のどちらか一方に決める方を推奨しています。理由は、両方を許すとClaudeにとって「どちらの経路で呼ぶべきか」の判断材料が減り、ツールの使い方に迷いが生まれるためです。
判断の具体例として、20人分の従業員の経費が予算内かをチェックするケースを考えます。従来のツール呼び出しでは、1人ずつ結果をコンテキストへ積みながら20往復のモデル呼び出しが発生し、数百件の経費明細行がそのままコンテキストに流れ込みます。経費照会ツールにallowed_callers: ["code_execution_20260120"]を付けておけば、Claudeは20人分の照会をまとめて1つのスクリプトとして書き、予算超過者だけを絞り込んだ結果をコンテキストに返せます。モデルが読む量は数百キロバイトから数行にまで縮みます。
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はあくまで「どのツールを使うか」を指定する仕組みで、「コード実行経由で呼ぶか、直接呼ぶか」までは制御できません。
input_schemaに自己参照する$ref(循環参照)を含むツールも、allowed_callersにコード実行バージョンを含めると400エラー(Circular $ref detected)になります。直接呼び出しなら同じスキーマでも通ります。回避策は2つで、そのツールだけallowed_callersを["direct"]のままにしておくか、再帰を固定の深さまで展開してスキーマから循環を取り除くかのどちらかです。MCPコネクタ経由のツールと、Computer use / Browser useのツールセットも、プログラマティックには呼び出せません(allowed_callersは"direct"しか受け付けません)。
公式ドキュメントが挙げる非互換機能はこれで全部ではありません。strict: trueを指定したStructured outputsのツールはプログラマティック呼び出しに対応しません。disable_parallel_tool_use: trueもプログラマティック呼び出しとは併用できません。
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の応答だけです。callerがcode_execution_20260120の呼び出しをトークン量で監査しようとして直接呼び出しと同じ数え方をすると、見かけ上のコストを過大に見積もることになります。
利用できる面を確認する — Bedrock・Google Cloudは非対応
プログラマティックツールコーリングは、Claude API・AWS上のClaude Platform・Microsoft Foundry(Hosted on Anthropicデプロイ限定)で使えます。Amazon BedrockとGoogle Cloudでは利用できません。コード実行ツール自体は使えても、allowed_callersによるプログラマティック呼び出しまでは対応していない、という切り分けです。
モデル側の制約もあります。Claude Haiku 4.5はcode_execution_20260120以降のツールバージョンをリクエストに含められますが、プログラマティックツールコーリングそのものはサポートしません。対応モデルはclaude-opus-5 / claude-sonnet-5 / claude-fable-5 / claude-mythos-5系と、Opus 4.5以降・Sonnet 4.5以降の各バージョンです。公式に明記されているHaikuモデルはHaiku 4.5のみで、それも上記のとおり対象外です。どの面・どのモデルで使うかを、実装前にこの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",
"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"]を付けるべきかどうかは、ワークロードの形で決まります。公式ドキュメントは、向く条件と向かない条件をそれぞれ具体的に挙げています。
向いている: 数十件規模のエンドポイント確認やレコード照会のようなファンアウト処理 / フィルタ・集計・要約してからコンテキストに渡すべき大きな結果 / 反復的な検索と結果の絞り込みが中心のエージェント検索。
向いていない: 各呼び出しがClaudeの前の結果への推論を必要とする、厳密に逐次的なワークフロー(スクリプトがモデルとの往復を省略できないため恩恵が出ない) / 会話の最初のターンなど、少数のツール呼び出しで結果も小さい場合(コンテナ起動とスクリプト生成のオーバーヘッドが節約分を上回る) / 呼び出しのたびに人間の確認を挟む必要があるツール。
Anthropicの社内評価では、75ツールを持つプロジェクト管理エージェントのベンチマークで、プログラマティックツールコーリングの有効化により課金対象の入力トークンが約38%減り、タスク精度は変わりませんでした。一方、1ターンにつき1〜2回しかツールを呼ばないτ²-benchでは、スコアは変わらずコストが約8%増えています。逐次的で呼び出し回数が少ないワークロードには効果が出ない、という数値です。実運用のトラフィックでは、tools配列に10〜49個のツール定義を含むリクエストで、20〜40%のトークン削減が典型的に観測されています。迷う場合は、allowed_callersを付けた場合と付けない場合で、代表的なトラフィックの課金対象トークンを実測してから広く適用するのが公式の推奨です。
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で、有効化にはbetas=["advanced-tool-use-2025-11-20"]のようなベータヘッダーの指定が必要でした。コード実行ツールの現行ドキュメントは、code_execution_20250825 / 20260120 / 20260521のいずれもanthropic-betaヘッダーを必要としないと明記しています。ツールバージョンが進み、ベータ運用の重さそのものが取れた、という位置づけで読めます。
まとめ
allowed_callersは["direct"] / ["code_execution_20260120"]のどちらか一方に決めるのが基本方針で、両方を許すのは特別な理由があるときだけに留めます。ファンアウト処理・大きな結果のフィルタリング・反復的な検索のように、コード側でまとめて処理した方が得なツールから優先的にcode_execution_20260120を検討し、逐次的で1回あたりの結果が小さいツールはdirectのままにする、という切り分けが出発点になります。tool_choiceで強制したいツールには必ず"direct"を含め、実行経路の追跡と課金内訳の把握にはcallerフィールドを使います。利用できる面(Claude API・AWS Claude Platform・Microsoft Foundryに限定、Bedrock・Google Cloudは非対応)と対応モデルも、実装前に必ず確認しておく項目です。周辺機能の全体像はAnthropic Advanced Tool Useを参照してください。サーバーツールとクライアントツールが同じターンに混在したときのstop_reasonの見分け方はtool_useとpause_turnの違いにまとめています。大量ツールを扱う場面でallowed_callersと組み合わせやすいもう1つの機能はAgent SDK Tool Searchの使い方です。