Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
「programmatic tool calling」（プログラムによるツール呼び出し）を使用すると、Claudeはツール呼び出しごとにモデルを経由するラウンドトリップを必要とせず、コード実行コンテナ内でツールをプログラム的に呼び出すコードを記述できます。これにより、複数ツールのワークフローにおける「latency」（レイテンシ）が削減され、データがモデルの「context window」（コンテキストウィンドウ）に到達する前にClaudeがデータをフィルタリングまたは処理できるため、トークン消費量も減少します。複数ステップのウェブリサーチや複雑な情報検索をテストするBrowseCompやDeepSearchQAなどのエージェント型検索ベンチマークでは、基本的な検索ツールにプログラムによるツール呼び出しを追加することで、入力トークンを24%削減しながらパフォーマンスが平均11%向上しました（動的フィルタリングによるウェブ検索の改善を参照）。
20人の従業員の予算遵守状況を確認する場合を考えてみましょう。従来のアプローチでは20回の個別のモデルラウンドトリップが必要で、その過程で数千件の経費明細がコンテキストに取り込まれます。プログラムによるツール呼び出しでは、1つのスクリプトが20件すべての検索を実行し、結果をフィルタリングして、上限を超えた従業員のみを返します。これにより、Claudeが推論する必要のある対象が数百キロバイトからわずか数行にまで縮小されます。
プログラムによるツール呼び出しにはcode_execution_20260120以降が必要で、以下のモデルでサポートされています。
| モデル |
|---|
| Claude Fable 5 () |
| Claude Mythos 5 () |
| Claude Opus 5 () |
| Claude Opus 4.8 () |
| Claude Opus 4.7 () |
| Claude Opus 4.6 () |
| Claude Sonnet 5 () |
| Claude Sonnet 4.6 () |
| Claude Opus 4.5 () |
| Claude Sonnet 4.5 () |
コード実行ツールの完全なバージョン対応表については、コード実行ツールのモデル互換性表を参照してください。プログラムによるツール呼び出しは、Claude API、Claude Platform on AWS、およびMicrosoft Foundryで利用できます。Microsoft Foundryでは、プログラムによるツール呼び出しにはHosted on Anthropicデプロイメントが必要です。現在、Amazon BedrockおよびGoogle Cloudでは利用できません。
以下は、Claudeがプログラム的にデータベースを複数回クエリし、結果を集計する例です。ツール定義にallowed_callers: ["code_execution_20260120"]を追加することで、そのツールがコード実行内から呼び出し可能になります（allowed_callersフィールドを参照）。
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-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_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"],
},
],
)
print(response)レスポンスはstop_reason: "tool_use"、container ID、およびquery_databaseのtool_useブロックとともに停止します。このブロックのcallerフィールドは、それを呼び出したコード実行を識別します。コードが完了できるように、ワークフロー例のステップ3に示すとおり結果を返してください。
ツールをコード実行から呼び出し可能に設定し、Claudeがそのツールが必要だと判断した場合：
tool_useブロックを返しますこのアプローチは特に以下の場合に有用です：
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"] - Claudeはこのツールをコード実行内からのみ呼び出すよう誘導されます["direct", "code_execution_20260120"] - Claudeはこのツールを直接またはコード実行内から呼び出すことができますallowed_callersでは"code_execution_20260120"と"code_execution_20260521"の両方が受け入れられ、相互に交換可能です。いずれかのコード実行ツールバージョンを使用するリクエストは、いずれかの呼び出し元をリストするツールの条件を満たします。レスポンスブロックは、リクエストがどのバージョンを宣言したかに関係なく、常に呼び出し元を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は呼び出しを行ったコード実行のserver_tool_useブロックのidであるため、各プログラムによるtool_useを、それを生成したコード実行と照合できます。
プログラムによるツール呼び出しは、コード実行と同じコンテナを使用します。
containerフィールドに、expires_atタイムスタンプとともに返されますexpires_atはコンテナの残り時間を示します。アイドル状態のコンテナは現在約5分後に回収され、作成から30日を超えたコンテナは再利用できません。プログラムによるツール呼び出しの完全なフローは以下のように動作します。
コード実行と、プログラムによる呼び出しを許可するツールを含むリクエストを送信します。プログラムによる呼び出しを有効にするには、ツール定義にallowed_callersフィールドを追加します。
リクエストの形式はクイックスタートの例と同一です。ツールリストにcode_executionを含め、Claudeにコードから呼び出させたいツールにallowed_callers: ["code_execution_20260120"]を追加し、ユーザーメッセージを送信します。このワークフローの残りのステップでは、ユーザーメッセージ"Query customer purchase history from the last quarter and identify our top 5 customers by revenue"を使用します。
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": "import json\n\nrows = json.loads(await query_database({'sql': '<sql>'}))\ntop_customers = sorted(rows, 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": "2026-01-20T14:30:00Z"
},
"stop_reason": "tool_use"
}完全な会話履歴とツール結果を送信します。このリクエストでは3つの点が重要です。
tool_resultブロックのみを含めることができます。メッセージ形式の制限を参照してください。container IDを渡します。APIは、保留中のプログラムによるツール呼び出しがあるにもかかわらずコンテナIDがない継続リクエストを拒否します。tools配列を送信します。一時停止したコードを再開するにはコード実行ツールが引き続き存在している必要があり、このリクエストで送信するツールは、ターンの残りの間Claudeと実行中のコードが使用できる定義となります。response = client.messages.create(
model="claude-opus-5",
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_20260120",
"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配列
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"],
},
],
)
print(response)コードは一時停止した箇所から再開し、結果を処理します。各継続レスポンスは、さらにプログラムによるtool_useブロックを伴って再び一時停止するか、コード実行を完了してClaudeにターンを続行させます（ステップ5）。この2つを区別するには、stop_reasonと各tool_useブロックのcallerを確認します。ユーザーの応答を待って一時停止するレスポンスにはstop_reason: "tool_use"と、callerがコード実行バージョンを示すtool_useブロックがあります。この場合、保留中のすべてのプログラムによる呼び出しに対するtool_resultを1つのユーザーメッセージに含めてステップ3を繰り返します。
コード実行が完了すると、Claudeは最終レスポンスを提供します。
{
"content": [
{
"type": "code_execution_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "code_execution_result",
"stdout": "Top 5 customers: [{'customer_id': 'C1', 'revenue': 45000}, {'customer_id': 'C2', 'revenue': 38000}, {'customer_id': 'C5', 'revenue': 32000}, {'customer_id': 'C8', 'revenue': 28500}, {'customer_id': 'C3', 'revenue': 24000}]",
"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:
rows = json.loads(await query_database({"sql": f"<sql for {region}>"}))
results[region] = sum(row["revenue"] for row in rows)
# 結果をプログラムで処理する
top_region = max(results.items(), key=lambda x: x[1])
print(f"Top region: {top_region[0]} with ${top_region[1]:,} in revenue")このパターンは：
Claudeは成功基準が満たされた時点で処理を停止できます。
endpoints = ["us-east", "eu-west", "apac"]
for endpoint in endpoints:
status = await check_health({"endpoint": endpoint})
if status == "healthy":
print(f"Found healthy endpoint: {endpoint}")
break # Stop early, don't check remainingpath = "/tmp/example.txt"
file_info = json.loads(await get_file_info({"path": path}))
if file_info["size"] < 10000:
content = await read_full_file({"path": path})
else:
content = await read_file_summary({"path": path})
print(content)server_id = "srv-01"
log_text = await fetch_logs({"server_id": server_id})
errors = [line for line in log_text.splitlines() if "ERROR" in line]
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 | レスポンス内のcode_execution_tool_resultエラーブロックのerror_code | コード実行ツールに無効なパラメータが渡されました | コード実行ツールのエラーを参照してください |
invalid_request_error（tool_choiceに関して） | HTTP 400エラーレスポンス | tool_choiceが、allowed_callersに"direct"を含まないツールを指定しています | そのツールのallowed_callersに"direct"を追加するか、tool_choiceからそのツールを削除してClaudeにコードから呼び出させてください |
ツール結果が約4分以内に届かない場合、保留中の呼び出しはClaudeの実行中のコード内で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 (no response after 270s).",
"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はプログラムによる呼び出しではサポートされませんinput_schemaに再帰的な$ref（自身を参照するスキーマなどの参照サイクル）を含むカスタムツールは、プログラムによる呼び出しを有効にできません。そのようなツールのallowed_callersにコード実行ツールバージョンを含めると、リクエストは400 invalid_request_errorで失敗し、そのメッセージにはCircular $ref detectedが含まれます。同じスキーマは直接のツール呼び出しでは受け入れられます。
これを回避するには、以下のいずれかを行ってください。
allowed_callersを省略する（または["direct"]に設定する）ことで、ツールを直接呼び出し専用にします。同じリクエスト内の他のツールは引き続きプログラムによる呼び出しを使用できます。descriptionで説明するか、再帰的なプロパティを、期待される形状をdescriptionで説明したプレーンな{"type": "object"}に置き換えます。以下のツールはプログラム的に呼び出すことができません。
computer_toolset_20260801およびbrowser_toolset_20260801）。これらのallowed_callersフィールドは"direct"のみを受け入れますプログラムによるツール呼び出しに応答する際には、厳格な形式要件があります。
ツール結果のみのレスポンス： 結果を待機している保留中のプログラムによるツール呼び出しがある場合、レスポンスメッセージには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}]"
}
]
}この制限は、プログラムによる（コード実行の）ツール呼び出しに応答する場合にのみ適用されます。通常のクライアント側ツール呼び出しでは、ツール結果の後にテキストコンテンツを含めることができます。
テキストのみのツール結果コンテンツ： プログラムによる呼び出しに応答する各tool_resultのcontentは、文字列またはtextブロックである必要があります。画像、ドキュメント、その他のコンテンツブロックタイプは拒否されます。
プログラムによるツール呼び出しは、通常のツール呼び出しと同じレート制限の対象となります。コード実行からの各ツール呼び出しは、個別の呼び出しとしてカウントされます。
プログラム的に呼び出されるユーザー定義ツールを実装する場合：
プログラムによるツール呼び出しは、3つの方法でトークン消費量を削減します。
たとえば、10個のツールを直接呼び出すと、プログラム的に呼び出して要約を返す場合の約10倍のトークンを使用します。
本番のClaudeモデルを使用したAnthropicの内部評価では：
tools配列に10〜49個のツール定義を含むリクエストで、プログラムによるツール呼び出しを有効にすると通常20%〜40%のトークン節約が見られます。実際の節約量はワークロードの形状によって異なります。プログラムによる呼び出しを使用すべき場合を参照してください。
プログラムによるツール呼び出しは、コード実行と同じ料金体系を使用します。詳細については、コード実行の料金を参照してください。
プログラムによるツール呼び出しは、小さな固定オーバーヘッド（コンテナの起動、スクリプト生成）と引き換えに、ツール結果トークンとモデルラウンドトリップを大幅に節約します。このトレードオフが有益かどうかは、ワークロードの形状によって異なります。
適している場合：
適していない場合：
判断がつかない場合は、広く有効にする前に、トラフィックの代表的なサンプルでallowed_callersの有無による課金対象の入力トークンを測定してください。
tool_choice設定時のinvalid_request_error
tool_choiceは、allowed_callersに"direct"が含まれていないツールを指定できません。そのツールのallowed_callersに"direct"を追加するか、tool_choiceからそのツールを削除してClaudeにコードから呼び出させてください。コンテナの有効期限切れ
expires_atタイムスタンプより十分前に、各プログラムによるツール呼び出しに応答してください。Claudeのコードは約4分後に結果の待機を停止し、アイドル状態のコンテナは現在約5分後に回収されます。ツール結果が正しく解析されない
callerフィールドを確認するClaudeは大量のコードで訓練されているため、ツールを呼び出し可能なPython関数として提示することで、その強みを活用できます。
プログラムによるツール呼び出しは、独自のインフラストラクチャでも実装できる汎用的なパターンです。各アプローチの比較は以下のとおりです。
Claudeにコード実行ツールを提供し、その環境で利用可能な関数を説明します。Claudeがコードでツールを呼び出すと、アプリケーションはそれらの関数が定義されているローカル環境でコードを実行します。
利点：
欠点：
使用すべき場合： アプリケーションが任意のコードを安全に実行でき、最小限の実装を望み、Anthropicのマネージドサービスがニーズに合わない場合。
Claudeの視点からは同じアプローチですが、コードはセキュリティ制限（たとえば、ネットワーク外部通信なし）のあるサンドボックス化されたコンテナで実行されます。ツールが外部リソースを必要とする場合、サンドボックス外でツール呼び出しを実行するためのプロトコルが必要になります。
利点：
欠点：
使用すべき場合： セキュリティが重要で、Anthropicのマネージドソリューションが要件に合わない場合。
Anthropicのプログラムによるツール呼び出しは、Claude向けに調整された独自のPython環境を備えた、サンドボックス実行のマネージド版です。Anthropicがコンテナ管理、コード実行、安全なツール呼び出し通信を処理します。
利点：
Claude API、Claude Platform on AWS、またはMicrosoft Foundryを使用している場合は、Anthropicのマネージドソリューションの使用を検討してください。Microsoft Foundryでは、プログラムによるツール呼び出しにはHosted on Anthropicデプロイメントが必要です。
プログラムによるツール呼び出しはコード実行インフラストラクチャ上に構築されており、同じサンドボックスコンテナを使用します。実行アーティファクトや出力を含むコンテナデータは、最大30日間保持されます。
すべての機能にわたるZDRの適格性については、APIとデータ保持を参照してください。
レイテンシに敏感なアプリケーション向けに、サーバー側のJSONバッファリングなしでツール入力をストリーミングします。
サンドボックス化されたコンテナでPythonとbashコードを実行し、データの分析、ファイルの生成、ソリューションの反復を行います。
Claudeを外部ツールやAPIに接続します。ツールがどこで実行されるか、Claudeがいつ呼び出すか、どのツールがタスクに適しているかを確認します。
ツールスキーマを指定し、効果的な説明を記述し、Claudeがツールを呼び出すタイミングを制御します。
Was this page helpful?