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

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

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

モデル互換性

プログラマティックツール呼び出しにはcode_execution_20260120が必要で、以下のモデルでサポートされています：

コード実行ツールの完全なバージョンマトリックスについては、コード実行ツールモデル互換性テーブルを参照してください。プログラマティックツール呼び出しはClaude APIおよびMicrosoft Foundryを通じて利用可能です。

クイックスタート

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

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

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

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

このアプローチは特に以下の場合に有用です：

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

コアコンセプト

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

レスポンスの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を渡してリクエスト間で状態を維持します

ワークフロー例

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

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

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

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

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

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

{
  "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は最終応答を提供します:

{
  "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": []
  }
}

エラーハンドリング

一般的なエラー

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

ツールの応答に時間がかかりすぎる場合、コード実行は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はコード内でツール結果を逆シリアル化するため、形式(JSON構造、フィールドタイプなど)を明確に文書化してください
• 構造化データを返してください: JSONまたは他の簡単に解析可能な形式がプログラマティック処理に最適です
• 応答を簡潔に保ってください: 処理オーバーヘッドを最小化するために必要なデータのみを返してください

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

適切なユースケース:

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

あまり理想的ではないユースケース:

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

パフォーマンス最適化

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

トラブルシューティング

一般的な問題

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

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

コンテナ有効期限切れ

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

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

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

デバッグのヒント

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

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

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

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

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

代替実装

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

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

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

利点:

• 最小限の再構築で実装が簡単です
• 環境と指示を完全に制御できます

欠点:

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

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

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

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

利点:

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

欠点:

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

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

Anthropic管理実行

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

利点:

• デフォルトで安全で保護されています
• 最小限の設定で有効にするのが簡単です
• Claudeに最適化された環境と指示

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

データ保持

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

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

関連機能