プログラマティックツール呼び出し

プログラマティックツール呼び出しにより、Claudeはコード実行コンテナ内でツールをプログラマティックに呼び出すコードを記述できます。これにより、ツール呼び出しのたびにモデルを経由するラウンドトリップが不要になります。マルチツールワークフローのレイテンシが低減され、Claudeがデータをフィルタリングまたは処理してからモデルのコンテキストウィンドウに到達させることで、トークン消費が削減されます。BrowseCompやDeepSearchQAなどのエージェント検索ベンチマーク（マルチステップのウェブ研究と複雑な情報検索をテストする）では、基本的な検索ツールの上にプログラマティックツール呼び出しを追加することが、エージェントパフォーマンスを完全に引き出すための重要な要因でした。

この差は実際のワークフローでは急速に複合します。20人の従業員の予算コンプライアンスをチェックする場合を考えてみてください。従来のアプローチでは20回の個別のモデルラウンドトリップが必要で、その過程で数千の経費行項目をコンテキストに引き込みます。プログラマティックツール呼び出しを使用すると、単一のスクリプトが20回のすべてのルックアップを実行し、結果をフィルタリングし、制限を超えた従業員のみを返します。これにより、Claudeが推論する必要があるものが数百キロバイトから数行に縮小されます。

プログラマティックツール呼び出しが対処する推論とコンテキストコストについてさらに詳しく知りたい場合は、高度なツール使用を参照してください。

この機能にはコード実行ツールが有効になっている必要があります。

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

モデル互換性

モデル互換性とツールバージョンの詳細については、ツールリファレンスを参照してください。プログラマティックツール呼び出しはClaude APIおよびMicrosoft Foundryを通じて利用可能です。

クイックスタート

Claudeがデータベースを複数回プログラマティックにクエリし、結果を集約する簡単な例を以下に示します。

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue"
            }
        ],
        "tools": [
            {
                "type": "code_execution_20260120",
                "name": "code_execution"
            },
            {
                "name": "query_database",
                "description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
                "input_schema": {
                    "type": "object",
                    "properties": {
                        "sql": {
                            "type": "string",
                            "description": "SQL query to execute"
                        }
                    },
                    "required": ["sql"]
                },
                "allowed_callers": ["code_execution_20260120"]
            }
        ]
    }'

プログラマティックツール呼び出しの仕組み

コード実行から呼び出し可能なツールを設定し、Claudeがそのツールを使用することを決定した場合：

Claudeはツールを関数として呼び出すPythonコードを記述します。複数のツール呼び出しと前処理/後処理ロジックが含まれる可能性があります
Claudeはこのコードをコード実行を介してサンドボックスコンテナで実行します
ツール関数が呼び出されると、コード実行が一時停止され、APIがtool_useブロックを返します
ツール結果を提供すると、コード実行が継続されます（中間結果はClaudeのコンテキストウィンドウに読み込まれません）
すべてのコード実行が完了すると、Claudeは最終出力を受け取り、タスクの処理を続行します

このアプローチは特に以下に役立ちます：

大規模データ処理： ツール結果をフィルタリングまたは集約してからClaudeのコンテキストに到達させます
マルチステップワークフロー： ツール呼び出し間でClaudeをサンプリングせずにツールを順序立てて、またはループで呼び出すことでトークンとレイテンシを節約します
条件付きロジック： 中間ツール結果に基づいて決定を下します

カスタムツールは並列ツール呼び出しをサポートするために非同期Python関数に変換されます。Claudeがコードを記述してツールを呼び出すとき、awaitを使用します（例：result = await query_database("<sql>")）。適切な非同期ラッパー関数が自動的に含まれます。

非同期ラッパーはこのドキュメントのコード例から明確にするために省略されています。

コアコンセプト

`allowed_callers`フィールド

allowed_callersフィールドは、どのコンテキストがツールを呼び出すことができるかを指定します：

{
  "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"] - 直接呼び出しとコード実行の両方から呼び出し可能

各ツールに対して["direct"]または["code_execution_20260120"]のいずれかを選択し、両方を有効にするのではなく、これはClaudeにツールの最適な使用方法についてより明確なガイダンスを提供します。

レスポンス内の`caller`フィールド

すべてのツール使用ブロックには、それがどのように呼び出されたかを示すcallerフィールドが含まれます：

直接呼び出し（従来のツール使用）：

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "query_database",
  "input": { "sql": "\<sql\>" },
  "caller": { "type": "direct" }
}

プログラマティック呼び出し：

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

tool_idはプログラマティック呼び出しを行ったコード実行ツールを参照します。

コンテナライフサイクル

プログラマティックツール呼び出しはコード実行と同じコンテナを使用します：

コンテナ作成： 既存のコンテナを再利用しない限り、セッションごとに新しいコンテナが作成されます
有効期限： コンテナの最大ライフタイムは30日で、4.5分のアイドル時間後にクリーンアップされます
コンテナID： レスポンスのcontainerフィールドを介して返されます
再利用： コンテナIDを渡してリクエスト間で状態を維持します

ツールがプログラマティックに呼び出され、コンテナがツール結果を待機している場合、コンテナの有効期限が切れる前に応答する必要があります。expires_atフィールドを監視してください。コンテナの有効期限が切れた場合、Claudeはツール呼び出しがタイムアウトしたと判断し、再試行する可能性があります。

ワークフロー例

完全なプログラマティックツール呼び出しフローがどのように機能するかを以下に示します：

ステップ1：初期リクエスト

コード実行とプログラマティック呼び出しを許可するツールを含むリクエストを送信します。プログラマティック呼び出しを有効にするには、ツール定義にallowed_callersフィールドを追加します。

ツールの出力形式の詳細な説明をツール説明に提供してください。ツールがJSONを返すことを指定した場合、Claudeは結果を逆シリアル化してコードで処理しようとします。出力スキーマについて提供する詳細が多いほど、Claudeはレスポンスをプログラマティックに処理できます。

リクエスト形状はクイックスタート例と同じです。ツールリストにcode_executionを含め、Claudeがコードから呼び出すようにしたいツールにallowed_callers: ["code_execution_20260120"]を追加し、ユーザーメッセージを送信します。

ステップ2：ツール呼び出しを含むAPIレスポンス

Claudeはツールを呼び出すコードを記述します。APIは一時停止して以下を返します：

Output

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll query the purchase history and analyze the results."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_abc123",
      "name": "code_execution",
      "input": {
        "code": "results = await query_database('<sql>')\ntop_customers = sorted(results, key=lambda x: x['revenue'], reverse=True)[:5]\nprint(f'Top 5 customers: {top_customers}')"
      }
    },
    {
      "type": "tool_use",
      "id": "toolu_def456",
      "name": "query_database",
      "input": { "sql": "\<sql\>" },
      "caller": {
        "type": "code_execution_20260120",
        "tool_id": "srvtoolu_abc123"
      }
    }
  ],
  "container": {
    "id": "container_xyz789",
    "expires_at": "2025-01-15T14:30:00Z"
  },
  "stop_reason": "tool_use"
}

ステップ3: ツール結果を提供する

完全な会話履歴とツール結果を含めます:

ステップ4: 次のツール呼び出しまたは完了

コード実行が続行され、結果が処理されます。追加のツール呼び出しが必要な場合は、すべてのツール呼び出しが満たされるまでステップ3を繰り返します。

ステップ5: 最終応答

コード実行が完了すると、Claudeは最終応答を提供します:

Output

{
  "content": [
    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_abc123",
      "content": {
        "type": "code_execution_result",
        "stdout": "Top 5 customers by revenue:\n1. Customer C1: $45,000\n2. Customer C2: $38,000\n3. Customer C5: $32,000\n4. Customer C8: $28,500\n5. Customer C3: $24,000",
        "stderr": "",
        "return_code": 0,
        "content": []
      }
    },
    {
      "type": "text",
      "text": "I've analyzed the purchase history from last quarter. Your top 5 customers generated $167,500 in total revenue, with Customer C1 leading at $45,000."
    }
  ],
  "stop_reason": "end_turn"
}

高度なパターン

ループを使用したバッチ処理

Claudeは複数のアイテムを効率的に処理するコードを記述できます:

async def _claude_code():
    regions = ["West", "East", "Central", "North", "South"]
    results = {}
    for region in regions:
        data = await query_database(f"<sql for {region}>")
        results[region] = sum(row["revenue"] for row in data)

    # Process results programmatically
    top_region = max(results.items(), key=lambda x: x[1])
    print(f"Top region: {top_region[0]} with ${top_region[1]:,} in revenue")

このパターンは:

モデルのラウンドトリップをN(地域ごとに1つ)から1に削減します
大きな結果セットをClaudeに返す前にプログラムで処理します
生データの代わりに集計された結論のみを返すことでトークンを節約します

早期終了

Claudeは成功基準が満たされるとすぐに処理を停止できます:

async def _claude_code():
    endpoints = ["us-east", "eu-west", "apac"]
    for endpoint in endpoints:
        status = await check_health(endpoint)
        if status == "healthy":
            print(f"Found healthy endpoint: {endpoint}")
            break  # Stop early, don't check remaining

条件付きツール選択

async def _claude_code():
    file_info = await get_file_info(path)
    if file_info["size"] < 10000:
        content = await read_full_file(path)
    else:
        content = await read_file_summary(path)
    print(content)

データフィルタリング

async def _claude_code():
    logs = await fetch_logs(server_id)
    errors = [log for log in logs if "ERROR" in log]
    print(f"Found {len(errors)} errors")
    for error in errors[-10:]:  # Only return last 10 errors
        print(error)

応答形式

プログラマティックツール呼び出し

コード実行がツールを呼び出すとき:

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": {
    "type": "code_execution_20260120",
    "tool_id": "srvtoolu_xyz789"
  }
}

ツール結果の処理

ツール結果は実行中のコードに返されます:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_abc123",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000, \"orders\": 23}, {\"customer_id\": \"C2\", \"revenue\": 38000, \"orders\": 18}, ...]"
    }
  ]
}

コード実行の完了

すべてのツール呼び出しが満たされ、コードが完了したとき:

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_xyz789",
  "content": {
    "type": "code_execution_result",
    "stdout": "Analysis complete. Top 5 customers identified from 847 total records.",
    "stderr": "",
    "return_code": 0,
    "content": []
  }
}

エラーハンドリング

一般的なエラー

エラー	説明	解決策
`invalid_tool_input`	ツール入力がスキーマと一致しない	ツールのinput_schemaを検証してください
`tool_not_allowed`	ツールが要求された呼び出し元タイプを許可していない	`allowed_callers`に正しいコンテキストが含まれていることを確認してください
`missing_beta_header`	必要なベータヘッダーが提供されていない(BedrockおよびVertex AIのみ。プログラマティックツール呼び出しはファーストパーティClaudeAPIではGAです)	要求に必要なベータヘッダーを追加してください

ツール呼び出し中のコンテナ有効期限

ツールの応答に時間がかかりすぎる場合、コード実行はTimeoutErrorを受け取ります。Claudeはこれをstderrで見て、通常は再試行します:

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "code_execution_result",
    "stdout": "",
    "stderr": "TimeoutError: Calling tool ['query_database'] timed out.",
    "return_code": 0,
    "content": []
  }
}

タイムアウトを防ぐには:

応答のexpires_atフィールドを監視してください
ツール実行のタイムアウトを実装してください
長い操作をより小さなチャンクに分割することを検討してください

ツール実行エラー

ツールがエラーを返す場合:

{
  "type": "tool_result",
  "tool_use_id": "toolu_abc123",
  "content": "Error: Query timeout - table lock exceeded 30 seconds"
}

Claudeのコードはこのエラーを受け取り、適切に処理できます。

制約と制限

機能の非互換性

構造化出力: strict: trueのツールはプログラマティック呼び出しではサポートされていません
ツール選択: tool_choiceを介して特定のツールのプログラマティック呼び出しを強制することはできません
並列ツール使用: disable_parallel_tool_use: trueはプログラマティック呼び出しではサポートされていません

ツール制限

以下のツールは現在プログラマティックに呼び出すことができませんが、将来のリリースでサポートが追加される可能性があります:

MCPコネクタによって提供されるツール

メッセージフォーマット制限

プログラマティックツール呼び出しに応答する場合、厳密なフォーマット要件があります:

ツール結果のみの応答: 結果を待つプログラマティックツール呼び出しが保留中の場合、応答メッセージにはのみ tool_resultブロックが含まれている必要があります。ツール結果の後でも、テキストコンテンツを含めることはできません。

無効 - プログラマティックツール呼び出しに応答するときはテキストを含めることはできません:

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

有効 - プログラマティックツール呼び出しに応答するときはツール結果のみ:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
    }
  ]
}

この制限は、プログラマティック(コード実行)ツール呼び出しに応答する場合にのみ適用されます。通常のクライアント側ツール呼び出しの場合、ツール結果の後にテキストコンテンツを含めることができます。

レート制限

プログラマティックツール呼び出しは、通常のツール呼び出しと同じレート制限の対象です。コード実行からのツール呼び出しはそれぞれ個別の呼び出しとしてカウントされます。

ツール結果を使用する前に検証する

プログラマティックに呼び出されるユーザー定義ツールを実装する場合:

ツール結果は文字列として返されます: コードスニペットや実行可能コマンドを含む任意のコンテンツを含めることができます。これは実行環境によって処理される可能性があります。
外部ツール結果を検証してください: ツールが外部ソースからデータを返す場合、またはユーザー入力を受け入れる場合、出力がコードとして解釈または実行される場合のコードインジェクションリスクに注意してください。

トークン効率

プログラマティックツール呼び出しはトークン消費を大幅に削減できます:

プログラマティック呼び出しからのツール結果はClaudeのコンテキストに追加されません - 最終的なコード出力のみが追加されます
中間処理はコードで発生します - フィルタリング、集計など、モデルトークンを消費しません
1つのコード実行での複数のツール呼び出し - 個別のモデルターンと比較してオーバーヘッドを削減します

たとえば、10個のツールを直接呼び出すと、プログラマティックに呼び出して概要を返すのと比べて約10倍のトークンを使用します。

使用とプライシング

プログラマティックツール呼び出しはコード実行と同じプライシングを使用します。詳細については、コード実行プライシングを参照してください。

プログラマティックツール呼び出しのトークンカウント: プログラマティック呼び出しからのツール結果は、入力/出力トークン使用量にカウントされません。最終的なコード実行結果とClaudeの応答のみがカウントされます。

ベストプラクティス

ツール設計

詳細な出力説明を提供してください: Claudeはコード内でツール結果を逆シリアル化するため、形式(JSON構造、フィールドタイプなど)を明確に文書化してください
構造化データを返してください: JSONまたは他の簡単に解析可能な形式がプログラマティック処理に最適です
応答を簡潔に保ってください: 処理オーバーヘッドを最小化するために必要なデータのみを返してください

プログラマティック呼び出しを使用する場合

良いユースケース:

集計または概要のみが必要な大規模データセットの処理
3つ以上の依存ツール呼び出しを含むマルチステップワークフロー
ツール結果のフィルタリング、ソート、または変換が必要な操作
中間データがClaudeの推論に影響を与えるべきではないタスク
多くのアイテム(例
)にわたる並列操作

理想的でないユースケース:

シンプルな応答を持つ単一のツール呼び出し
即座のユーザーフィードバックが必要なツール
コード実行のオーバーヘッドが利益を上回る非常に高速な操作

パフォーマンス最適化

複数の関連リクエストを行う場合はコンテナを再利用して 状態を維持してください
可能な場合は単一のコード実行で同様の操作をバッチ処理してください

トラブルシューティング

一般的な問題

「ツールが許可されていない」エラー

ツール定義に"allowed_callers": ["code_execution_20260120"]が含まれていることを確認してください

コンテナ有効期限

コンテナがアイドルアウトする前にツール呼び出しに応答してください(非アクティブ4.5分、30日間のハード最大値)
応答のexpires_atフィールドを監視してください
より高速なツール実行の実装を検討してください

ツール結果が正しく解析されない

ツールが文字列データを返し、Claudeが逆シリアル化できることを確認してください
ツール説明に明確な出力形式ドキュメントを提供してください

デバッグのヒント

すべてのツール呼び出しと結果をログに記録して フローを追跡してください
callerフィールドを確認して プログラマティック呼び出しを確認してください
コンテナIDを監視して 適切な再利用を確認してください
プログラマティック呼び出しを有効にする前にツールを独立してテストしてください

プログラマティックツール呼び出しが機能する理由

Claudeのトレーニングにはコードへの広範な露出が含まれており、関数呼び出しの推論と連鎖に効果的です。ツールがコード実行環境内で呼び出し可能な関数として提示されると、Claudeはこの強みを活用して:

ツール構成について自然に推論してください: 操作を連鎖させ、依存関係を処理し、Pythonコードを記述するのと同じくらい自然に依存関係を処理してください
大きな結果を効率的に処理してください: 大きなツール出力をフィルタリングし、関連データのみを抽出し、または中間結果をファイルに書き込んでから概要をコンテキストウィンドウに返してください
レイテンシを大幅に削減してください: マルチステップワークフローの各ツール呼び出し間でClaudeを再サンプリングするオーバーヘッドを排除してください

このアプローチにより、Claudeがデータをプログラマティックに処理できるようにすることで、すべてを会話コンテキストに読み込むのではなく、従来のツール使用では実用的でないワークフロー(1M以上のトークンを超えるファイルの処理など)が可能になります。

代替実装

プログラマティックツール呼び出しは、Anthropicの管理されたコード実行の外で実装できる一般化可能なパターンです。以下はアプローチの概要です:

クライアント側の直接実行

Claudeにコード実行ツールを提供し、その環境で利用可能な関数について説明してください。Claudeがコードでツールを呼び出すと、アプリケーションはそれらの関数が定義されているローカルで実行します。

利点:

最小限の再アーキテクチャで実装が簡単
環境と指示の完全な制御

欠点:

サンドボックスの外で信頼されていないコードを実行します
ツール呼び出しはコードインジェクションのベクトルになる可能性があります

使用する場合: アプリケーションが安全に任意のコードを実行できる場合、シンプルなソリューションが必要な場合、およびAnthropicの管理されたオファリングがニーズに合わない場合。

自己管理サンドボックス実行

Claudeの観点からは同じアプローチですが、コードはセキュリティ制限(ネットワーク出力なしなど)を備えたサンドボックスコンテナで実行されます。ツールが外部リソースを必要とする場合、サンドボックスの外でツール呼び出しを実行するためのプロトコルが必要です。

利点:

独自のインフラストラクチャでセキュアなプログラマティックツール呼び出し
実行環境の完全な制御

欠点:

構築と保守が複雑
インフラストラクチャとプロセス間通信の両方を管理する必要があります

使用する場合: セキュリティが重要で、Anthropicの管理されたソリューションがニーズに合わない場合。

Anthropic管理実行

Anthropicのプログラマティックツール呼び出しは、サンドボックス実行の管理されたバージョンで、Claudeに合わせて調整されたPython環境を備えています。Anthropicはコンテナ管理、コード実行、およびセキュアなツール呼び出し通信を処理します。

利点:

デフォルトで安全でセキュア
最小限の設定で簡単に有効化
Claudeに最適化された環境と指示

Claude APIを使用している場合は、Anthropicの管理されたソリューションの使用を検討してください。

データ保持

プログラマティックツール呼び出しはコード実行インフラストラクチャ上に構築され、同じサンドボックスコンテナを使用します。実行アーティファクトと出力を含むコンテナデータは最大30日間保持されます。

すべての機能にわたるZDR適格性については、APIとデータ保持を参照してください。

モデル互換性

クイックスタート

プログラマティックツール呼び出しの仕組み

コアコンセプト

allowed_callersフィールド

レスポンス内のcallerフィールド

コンテナライフサイクル

ワークフロー例

ステップ1：初期リクエスト

ステップ2：ツール呼び出しを含むAPIレスポンス

ステップ3: ツール結果を提供する

ステップ4: 次のツール呼び出しまたは完了

ステップ5: 最終応答

高度なパターン

ループを使用したバッチ処理

早期終了

条件付きツール選択

データフィルタリング

応答形式

プログラマティックツール呼び出し

ツール結果の処理

コード実行の完了

エラーハンドリング

一般的なエラー

ツール呼び出し中のコンテナ有効期限

ツール実行エラー

制約と制限

機能の非互換性

ツール制限

メッセージフォーマット制限

レート制限

ツール結果を使用する前に検証する

トークン効率

使用とプライシング

ベストプラクティス

ツール設計

プログラマティック呼び出しを使用する場合

パフォーマンス最適化

トラブルシューティング

一般的な問題

デバッグのヒント

プログラマティックツール呼び出しが機能する理由

代替実装

クライアント側の直接実行

自己管理サンドボックス実行

Anthropic管理実行

データ保持

関連機能

`allowed_callers`フィールド

レスポンス内の`caller`フィールド