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

> Programmatic Tool Callingは複数ツール呼び出しをコード実行に集約し、公式評価で入力トークンを約38%削減した。allowed_callersの統制設計を整理する。

- Canonical: https://kuucorp.com/blog/programmatic-tool-calling-allowed-callers-governance-design/
- Date: 2026-10-10
- Last modified: 2026-10-10
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
在庫・課金・監査ログと数十の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）](https://kuucorp.com/services/rde/)の枠組みで内製チームと伴走できる。ツール数が多い場合は、[Tool Searchによる定義の絞り込み](/blog/agent-tool-search-defer-loading-design/)と併用すると、定義と結果の両面でトークンを抑えられる。コード実行の隔離は[ツール実行サンドボックスの設計](/blog/tool-execution-sandbox-isolation-design/)も参照したい。

## 参考

- [Programmatic tool calling（Claude Platform Docs）](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)
- [Introducing advanced tool use（Anthropic Engineering）](https://www.anthropic.com/engineering/advanced-tool-use)

## まとめ

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