ツール

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

Claudeがコード実行コンテナ内でツールをプログラマティックに呼び出すコードを記述できるようにします

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

プログラマティックツール呼び出しは現在パブリックベータ版です。

この機能を使用するには、API リクエストに "advanced-tool-use-2025-11-20" ベータヘッダーを追加してください。

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

モデル互換性

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

モデル	ツールバージョン
Claude Opus 4.5 (`claude-opus-4-5-20251101`)	`code_execution_20250825`
Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`)	`code_execution_20250825`

プログラマティックツール呼び出しは 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 "anthropic-beta: advanced-tool-use-2025-11-20" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5",
        "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_20250825",
                "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_20250825"]
            }
        ]
    }'

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

コード実行から呼び出し可能なツールを構成し、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_20250825"]
}

可能な値：

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

各ツールに対して ["direct"] または ["code_execution_20250825"] のいずれかを選択し、両方を有効にしないことをお勧めします。これにより、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_20250825",
    "tool_id": "srvtoolu_abc123"
  }
}

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

コンテナライフサイクル

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

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

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

ワークフロー例

完全なプログラマティックツール呼び出しフローの仕組みを以下に示します：

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

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

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

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Query customer purchase history from the last quarter and identify our top 5 customers by revenue"
    }],
    tools=[
        {
            "type": "code_execution_20250825",
            "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": {...},
            "allowed_callers": ["code_execution_20250825"]
        }
    ]
)

ステップ 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：ツール結果を提供

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

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=4096,
    container="container_xyz789",  # Reuse the container
    messages=[
        {"role": "user", "content": "Query customer purchase history from the last quarter and identify our top 5 customers by revenue"},
        {
            "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": "..."}
                },
                {
                    "type": "tool_use",
                    "id": "toolu_def456",
                    "name": "query_database",
                    "input": {"sql": "<sql>"},
                    "caller": {
                        "type": "code_execution_20250825",
                        "tool_id": "srvtoolu_abc123"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_def456",
                    "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}, {\"customer_id\": \"C2\", \"revenue\": 38000}, ...]"
                }
            ]
        }
    ],
    tools=[...]
)

ステップ 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 wrapper omitted for clarity
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 wrapper omitted for clarity
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 wrapper omitted for clarity
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 wrapper omitted for clarity
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_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": []
  }
}

エラーハンドリング

一般的なエラー

エラー	説明	ソリューション
`invalid_tool_input`	ツール入力がスキーマと一致しない	ツールの input_schema を検証してください
`tool_not_allowed`	ツールが要求された呼び出し元タイプを許可していない	`allowed_callers` に正しいコンテキストが含まれているか確認してください
`missing_beta_header`	PTC ベータヘッダーが提供されていない	リクエストに両方のベータヘッダーを追加してください

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

ツールの応答に時間がかかりすぎる場合、コード実行は 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 フィールドを監視してください
ツール実行のタイムアウトを実装してください
長時間の操作をより小さなチャンクに分割することを検討してください

ツール実行エラー

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

# Provide error information in the tool result
{
    "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?"}  // This will cause an error
  ]
}

// ✅ 有効 - プログラマティックツール呼び出しに応答するときはツール結果のみ
{
  "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 の推論に影響を与えるべきではないタスク
多くのアイテム（例：50 個のエンドポイントをチェック）にわたる並列操作

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

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

パフォーマンス最適化

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

トラブルシューティング

一般的な問題

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

ツール定義に "allowed_callers": ["code_execution_20250825"] が含まれていることを確認してください
正しいベータヘッダーを使用していることを確認してください

コンテナ有効期限切れ

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

ベータヘッダーの問題

ヘッダーが必要です："advanced-tool-use-2025-11-20"

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

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

デバッグのヒント

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

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

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

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

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

代替実装

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

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

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

利点：

最小限の再アーキテクチャで実装が簡単です
環境と命令を完全に制御できます

欠点：

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

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

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

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

利点：

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

欠点：

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

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

Anthropic 管理実行

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

利点：

デフォルトで安全かつセキュアです
最小限の構成で簡単に有効にできます
Claude 用に最適化された環境と命令です

Claude API を使用している場合は、Anthropic の管理されたソリューションを使用することをお勧めします。

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

Claudeがコード実行コンテナ内でツールをプログラマティックに呼び出すコードを記述できるようにします

プログラマティックツール呼び出しは現在パブリックベータ版です。

この機能を使用するには、API リクエストに "advanced-tool-use-2025-11-20" ベータヘッダーを追加してください。

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

モデル互換性

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

モデル	ツールバージョン
Claude Opus 4.5 (`claude-opus-4-5-20251101`)	`code_execution_20250825`
Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`)	`code_execution_20250825`

プログラマティックツール呼び出しは 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 "anthropic-beta: advanced-tool-use-2025-11-20" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5",
        "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_20250825",
                "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_20250825"]
            }
        ]
    }'

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

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

Claude はツールを関数として呼び出す Python コードを記述します。複数のツール呼び出しと前処理/後処理ロジックが含まれる可能性があります
Claude はこのコードをコード実行経由のサンドボックスコンテナで実行します
ツール関数が呼び出されると、コード実行が一時停止され、API は tool_use ブロックを返します
ツール結果を提供すると、コード実行が継続します（中間結果は Claude のコンテキストウィンドウに読み込まれません）
すべてのコード実行が完了すると、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：初期リクエスト

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Query customer purchase history from the last quarter and identify our top 5 customers by revenue"
    }],
    tools=[
        {
            "type": "code_execution_20250825",
            "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": {...},
            "allowed_callers": ["code_execution_20250825"]
        }
    ]
)

ステップ 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：ツール結果を提供

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

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=4096,
    container="container_xyz789",  # Reuse the container
    messages=[
        {"role": "user", "content": "Query customer purchase history from the last quarter and identify our top 5 customers by revenue"},
        {
            "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": "..."}
                },
                {
                    "type": "tool_use",
                    "id": "toolu_def456",
                    "name": "query_database",
                    "input": {"sql": "<sql>"},
                    "caller": {
                        "type": "code_execution_20250825",
                        "tool_id": "srvtoolu_abc123"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_def456",
                    "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}, {\"customer_id\": \"C2\", \"revenue\": 38000}, ...]"
                }
            ]
        }
    ],
    tools=[...]
)

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

ステップ 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 wrapper omitted for clarity
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 wrapper omitted for clarity
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 wrapper omitted for clarity
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 wrapper omitted for clarity
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_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": []
  }
}

エラーハンドリング

一般的なエラー

エラー	説明	ソリューション
`invalid_tool_input`	ツール入力がスキーマと一致しない	ツールの input_schema を検証してください
`tool_not_allowed`	ツールが要求された呼び出し元タイプを許可していない	`allowed_callers` に正しいコンテキストが含まれているか確認してください
`missing_beta_header`	PTC ベータヘッダーが提供されていない	リクエストに両方のベータヘッダーを追加してください

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

ツールの応答に時間がかかりすぎる場合、コード実行は 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 フィールドを監視してください
ツール実行のタイムアウトを実装してください
長時間の操作をより小さなチャンクに分割することを検討してください

ツール実行エラー

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

# Provide error information in the tool result
{
    "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 コネクタによって提供されるツール

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

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

// ❌ 無効 - プログラマティックツール呼び出しに応答するときにテキストを含めることはできません
{
  "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?"}  // This will cause an error
  ]
}

// ✅ 有効 - プログラマティックツール呼び出しに応答するときはツール結果のみ
{
  "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 個のエンドポイントをチェック）にわたる並列操作

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

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

パフォーマンス最適化

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

トラブルシューティング

一般的な問題

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

ツール定義に "allowed_callers": ["code_execution_20250825"] が含まれていることを確認してください
正しいベータヘッダーを使用していることを確認してください

コンテナ有効期限切れ

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

ベータヘッダーの問題

ヘッダーが必要です："advanced-tool-use-2025-11-20"

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

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

デバッグのヒント

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

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

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

代替実装

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

利点：

最小限の再アーキテクチャで実装が簡単です
環境と命令を完全に制御できます

欠点：

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

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

利点：

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

欠点：

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

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

Anthropic 管理実行

利点：

デフォルトで安全かつセキュアです
最小限の構成で簡単に有効にできます
Claude 用に最適化された環境と命令です

Claude API を使用している場合は、Anthropic の管理されたソリューションを使用することをお勧めします。

モデル互換性

クイックスタート

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

コアコンセプト

allowed_callers フィールド

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

コンテナライフサイクル

ワークフロー例

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

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

ステップ 3：ツール結果を提供

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

ステップ 5：最終レスポンス

高度なパターン

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

早期終了

条件付きツール選択

データフィルタリング

レスポンス形式

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

ツール結果処理

コード実行完了

エラーハンドリング

一般的なエラー

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

ツール実行エラー

制約と制限

機能の非互換性

ツール制限

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

レート制限

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

トークン効率

使用とプライシング

ベストプラクティス

ツール設計

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

パフォーマンス最適化

トラブルシューティング

一般的な問題

デバッグのヒント

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

代替実装

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

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

Anthropic 管理実行

関連機能

モデル互換性

クイックスタート

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

コアコンセプト

allowed_callers フィールド

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

コンテナライフサイクル

ワークフロー例

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

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

ステップ 3：ツール結果を提供

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

ステップ 5：最終レスポンス

高度なパターン

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

早期終了

条件付きツール選択

データフィルタリング

レスポンス形式

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

ツール結果処理

コード実行完了

エラーハンドリング

一般的なエラー

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

ツール実行エラー

制約と制限

機能の非互換性

ツール制限

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

レート制限

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

トークン効率

`allowed_callers` フィールド

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

`allowed_callers` フィールド

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