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

プログラマティックツール呼び出しにより、Claudeは各ツール呼び出しごとにモデルとのラウンドトリップを必要とせず、コード実行コンテナ内でプログラム的にツールを呼び出すコードを記述できます。これにより、マルチツールワークフローのレイテンシーが削減され、Claudeがモデルのコンテキストウィンドウに到達する前にデータをフィルタリングまたは処理できるため、トークン消費量が減少します。

モデルの互換性

プログラマティックツール呼び出しは以下のモデルで利用可能です：

クイックスタート

以下は、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_20250825"]
}

指定可能な値：

• ["direct"] - Claudeのみがこのツールを直接呼び出せます（省略時のデフォルト）
• ["code_execution_20250825"] - コード実行内からのみ呼び出し可能
• ["direct", "code_execution_20250825"] - 直接およびコード実行の両方から呼び出し可能

レスポンスの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_20250825",
    "tool_id": "srvtoolu_abc123"
  }
}

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

コンテナのライフサイクル

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

• コンテナの作成：既存のコンテナを再利用しない限り、各セッションごとに新しいコンテナが作成されます
• 有効期限：コンテナは約4.5分間の非アクティブ後に期限切れになります（変更される可能性があります）
• コンテナID：containerフィールドを通じてレスポンスで返されます
• 再利用：リクエスト間で状態を維持するためにコンテナIDを渡します

ワークフローの例

プログラマティックツール呼び出しの完全なフローは以下のように動作します：

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

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

ステップ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_20250825",
        "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は複数のアイテムを効率的に処理するコードを記述できます：

# わかりやすさのために非同期ラッパーは省略
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)

# 結果をプログラム的に処理
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は成功基準が満たされた時点で処理を停止できます：

# わかりやすさのために非同期ラッパーは省略
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  # 早期停止、残りはチェックしない

条件付きツール選択

# わかりやすさのために非同期ラッパーは省略
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)

データフィルタリング

# わかりやすさのために非同期ラッパーは省略
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:]:  # 最後の10件のエラーのみ返す
    print(error)

レスポンス形式

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

コード実行がツールを呼び出す場合：

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "query_database",
  "input": {"sql": "<sql>"},
  "caller": {
    "type": "code_execution_20250825",
    "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はプログラマティック呼び出しではサポートされていません

ツールの制限

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

• Web検索
• Webフェッチ
• 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の推論に影響を与えるべきでないタスク
• 多数のアイテムにわたる並列操作（例：50のエンドポイントのチェック）

あまり適さない使用ケース：

• シンプルなレスポンスを伴う単一のツール呼び出し
• 即座のユーザーフィードバックが必要なツール
• コード実行のオーバーヘッドが利点を上回るような非常に高速な操作

パフォーマンス最適化

• 関連する複数のリクエストを行う際に状態を維持するためにコンテナを再利用する
• 可能な場合は類似の操作を1回のコード実行にバッチ処理する

トラブルシューティング

一般的な問題

「Tool not allowed」エラー

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

コンテナの期限切れ

• コンテナのライフタイム（約4.5分）内にツール呼び出しに応答するようにしてください
• レスポンスのexpires_atフィールドを監視してください
• より高速なツール実行の実装を検討してください

ツール結果が正しくパースされない

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

デバッグのヒント

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

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

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

• ツールの組み合わせについて自然に推論する：通常のPythonコードを書くのと同じように自然に操作をチェーンし、依存関係を処理する
• 大規模な結果を効率的に処理する：大きなツール出力をフィルタリングし、関連データのみを抽出するか、コンテキストウィンドウにサマリーを返す前に中間結果をファイルに書き込む
• レイテンシーを大幅に削減する：マルチステップワークフローで各ツール呼び出し間でClaudeを再サンプリングするオーバーヘッドを排除する

このアプローチにより、1Mトークンを超えるファイルの処理など、従来のツール使用では実用的でなかったワークフローが可能になります。すべてを会話コンテキストにロードするのではなく、Claudeがプログラム的にデータを操作できるようにすることで実現されます。

代替実装

プログラマティックツール呼び出しは、Anthropicのマネージドコード実行の外部でも実装できる汎用的なパターンです。以下はアプローチの概要です：

クライアントサイド直接実行

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

利点：

• 最小限の再設計で簡単に実装できる
• 環境と指示を完全に制御できる

欠点：

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

使用するタイミング： アプリケーションが任意のコードを安全に実行でき、シンプルなソリューションが必要で、Anthropicのマネージドオファリングがニーズに合わない場合。

セルフマネージドサンドボックス実行

Claudeの観点からは同じアプローチですが、コードはセキュリティ制限（例：ネットワークエグレスなし）を持つサンドボックスコンテナ内で実行されます。ツールが外部リソースを必要とする場合、サンドボックスの外でツール呼び出しを実行するためのプロトコルが必要です。

利点：

• 自社インフラストラクチャ上での安全なプログラマティックツール呼び出し
• 実行環境を完全に制御できる

欠点：

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

使用するタイミング： セキュリティが重要で、Anthropicのマネージドソリューションが要件に合わない場合。

Anthropicマネージド実行

Anthropicのプログラマティックツール呼び出しは、Claude向けに最適化されたPython環境を備えたサンドボックス実行のマネージドバージョンです。Anthropicがコンテナ管理、コード実行、および安全なツール呼び出し通信を処理します。

利点：

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

Claude APIを使用している場合は、Anthropicのマネージドソリューションの使用をお勧めします。

関連機能