プログラム的ツール呼び出しの設計と統制

在庫・課金・監査ログと数十のAPIを束ねる社内エージェントで、1回の集計のたびにモデル往復が20回走り、明細が延々とコンテキストに積み上がる。ツールが増えるほど、遅延とトークンコストはツール呼び出しの回数に比例して膨らむ。Programmatic Tool Calling（PTC）は、この往復をコード実行に畳み込む仕組みだ。

プログラム的ツール呼び出しとは何か

PTCはClaudeが書いたPythonがコード実行コンテナ内でツールを呼ぶ仕組みで、中間結果がコンテキストに入りません。

通常のツール呼び出しは、1回ごとにモデルが推論し、結果をそのままコンテキストへ戻す。PTCではClaudeがPythonコードを生成し、サンドボックス化されたコンテナで実行する。コードがツール関数を呼ぶたびに実行が一時停止し、APIが tool_use ブロックを返す。クライアントが結果を返すとコードが再開し、全処理の完了後に最終出力だけがClaudeへ渡る。

ツールは非同期のPython関数として公開されるため、asyncio.gather による並列実行もできる。ループ・条件分岐・集計がモデルの再サンプリングなしで完結する点が本質だ。前提は code_execution_20260120 以降のコード実行ツールで、対応モデルは公式ドキュメントの一覧で確認する。

どのワークロードで効果が出るのか

公式評価では75ツールの構成で入力トークンが約38%減ったが、逐次の単発呼び出しでは約8%増えました。

公式ドキュメントが示す数値は次のとおりだ。

• 75ツールのプロジェクト管理エージェントのベンチマーク: 課金入力トークンが約38%減少、精度は変化なし
• τ²-bench（各ターン1〜2回の逐次呼び出し）: スコアは不変、コストは約8%増加
• 本番トラフィックでツール定義が10〜49個のリクエスト: 典型的に20〜40%の削減

向くのは、多数の対象への扇形の呼び出し（50エンドポイントの確認など）、大きな結果を絞り込んでから渡したい処理、反復的な検索だ。向かないのは、前の結果をモデルが毎回判断する厳密な逐次処理や、小さな応答が少数あるだけの処理で、コンテナ起動とスクリプト生成の固定オーバーヘッドが勝る。導入前に allowed_callers の有無で課金入力トークンを実トラフィックで比較する。

allowed_callersをどう設計するか

allowed_callers は各ツールの呼び出し元を指定する設定で、direct とコード実行のどちらかに寄せるのが推奨です。

ツール定義に "allowed_callers": ["code_execution_20260120"] を付けると、そのツールはコード内から呼べる。省略時は ["direct"] だ。両方を指定することもできるが、公式はClaudeへの指針を明確にするため、ツールごとにどちらか一方を選ぶよう勧めている。

分類の目安は次の2つだ。

1. コード側に寄せる: 参照系で結果が大きく、集計・フィルタ前提のツール（明細取得、ログ検索）
2. direct に残す: 副作用があり、人間の承認や個別判断を挟みたいツール（送金、権限変更、削除）

統制上の最重要点がある。allowed_callers は提示方法の制御であり、API側の強制ブロックではない。公式は「セキュリティ境界として頼らない」と明記している。クライアントは、定義した任意のツールに direct の tool_use が来ても処理できる必要がある。実行可否の判定は、ポリシーエンジンや権限チェックを自前のツール実行層に置く。

運用で何を制御するか

caller フィールドで呼び出し元を記録し、コンテナの有効期限と約4分のタイムアウトを監視に組み込みます。

各 tool_use ブロックには caller が付く。直接呼び出しなら {"type": "direct"}、PTCなら code_execution_20260120 と tool_id が入る。tool_id は該当コード実行の server_tool_use の id なので、監査ログに記録すれば「どのコード実行がどのツールを何回呼んだか」を追跡できる。

運用上の制約も押さえる。

• 結果待ちの間はコンテナIDの指定が必須で、結果待ちが約4分を超えると、コード内で TimeoutError が発生する
• アイドルのコンテナは約5分で回収され、作成から30日を超えて再利用はできない
• 応答メッセージには tool_result だけを入れる（テキストの併記は不可）
• strict: true のツール、MCPコネクタ経由のツール、computer use・browser useのツールセットは対象外
• ZDR（ゼロデータ保持）の対象外で、コンテナデータは最大30日保持される

ツール結果は文字列としてコード実行環境に渡る。外部入力を含む結果は、コードとして解釈されるリスクがあるため検証してから返す。レート制限は通常のツール呼び出しと同じで、コード内の1回の呼び出しが1回として数えられる。

規模別にどう導入を進めるか

エンタープライズでは、対象ツールの分類、監査ログ、ZDR要件の確認を導入前に済ませます。

大規模環境では、ツールカタログ単位で「コード側に寄せる」「direct 固定」を台帳化し、変更をレビュー対象にする。ZDRが契約要件なら、PTCは対象外なので適用範囲から外す。自社基盤でコード実行を管理したい場合は、ネットワーク遮断のサンドボックスと、ツール呼び出しのブリッジを自作する選択肢もあるが、構築・保守の負荷は大きい。設計と統制の整備は、RDE（Reinvention Deployed Engineering）の枠組みで内製チームと伴走できる。ツール数が多い場合は、Tool Searchによる定義の絞り込みと併用すると、定義と結果の両面でトークンを抑えられる。コード実行の隔離はツール実行サンドボックスの設計も参照したい。

参考

• Programmatic tool calling（Claude Platform Docs）
• Introducing advanced tool use（Anthropic Engineering）

まとめ

PTCは、大きな結果の絞り込みや多数対象への呼び出しでトークンと往復を減らす一方、逐次の単発呼び出しではコスト増になり得ます。allowed_callers は境界ではなく指針なので、権限判定は自前の実行層に置き、caller を監査ログに残してください。ツール分類や適用判断の設計でお困りの場合は、Kuu株式会社のRDEへご相談ください。