程式化工具呼叫

程式化工具呼叫讓 Claude 能夠在程式碼執行容器中撰寫程式碼來程式化地呼叫您的工具，而不需要每次工具呼叫都透過模型進行往返。這減少了多工具工作流程的延遲，並透過讓 Claude 在資料進入模型的上下文視窗之前進行過濾或處理，降低了 token 消耗。在像 BrowseComp 和 DeepSearchQA 這樣的代理搜尋基準測試中（這些測試涉及多步驟網路研究和複雜資訊檢索），在基本搜尋工具之上加入程式化工具呼叫是完全釋放代理效能的關鍵因素。

這種差異在實際工作流程中會快速累積。考慮檢查 20 名員工的預算合規性：傳統方法需要 20 次獨立的模型往返，同時將數千筆費用明細拉入上下文。使用程式化工具呼叫，單一腳本執行所有 20 次查詢、過濾結果，並只返回超出限額的員工，將 Claude 需要推理的內容從數百 KB 縮減到幾行。

若要深入了解程式化工具呼叫所解決的推理和上下文成本問題，請參閱進階工具使用。

此功能需要啟用程式碼執行工具。

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 進行取樣，節省 token 和延遲
條件邏輯： 根據中間工具結果做出決策

自訂工具會被轉換為非同步 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，將 allowed_callers: ["code_execution_20260120"] 加入您希望 Claude 從程式碼呼叫的任何工具，並發送您的使用者訊息。

步驟 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 次
在返回 Claude 之前以程式方式處理大型結果集
僅返回彙總結論而非原始資料，從而節省 token

提前終止

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`	未提供必要的 beta 標頭（僅限 Bedrock 和 Vertex AI；程式化工具呼叫在第一方 Claude API 上已正式發布）	在您的請求中添加必要的 beta 標頭

工具呼叫期間容器過期

如果您的工具回應時間過長，程式碼執行會收到 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}]"
    }
  ]
}

此限制僅適用於回應程式化（程式碼執行）工具呼叫時。對於一般的客戶端工具呼叫，您可以在工具結果之後包含文字內容。

速率限制

程式化工具呼叫受到與一般工具呼叫相同的速率限制。來自程式碼執行的每個工具呼叫都算作單獨的調用。

使用前驗證工具結果

在實作將以程式方式呼叫的使用者定義工具時：

工具結果以字串形式返回： 它們可以包含任何內容，包括可能由執行環境處理的程式碼片段或可執行命令。
驗證外部工具結果： 如果您的工具從外部來源返回資料或接受使用者輸入，請注意如果輸出將被解釋或作為程式碼執行，則存在程式碼注入風險。

Token 效率

程式化工具呼叫可以顯著減少 token 消耗：

程式化呼叫的工具結果不會添加到 Claude 的上下文中 - 只有最終程式碼輸出才會
中間處理在程式碼中進行 - 過濾、彙總等不消耗模型 token
在一次程式碼執行中進行多個工具呼叫 - 與單獨的模型輪次相比減少了開銷

例如，直接呼叫 10 個工具使用的 token 約為以程式方式呼叫並返回摘要的 10 倍。

使用量與定價

程式化工具呼叫使用與程式碼執行相同的定價。詳情請參閱程式碼執行定價。

程式化工具呼叫的 token 計算：程式化調用的工具結果不計入您的輸入/輸出 token 使用量。只有最終程式碼執行結果和 Claude 的回應才計算在內。

最佳實踐

工具設計

提供詳細的輸出說明： 由於 Claude 在程式碼中反序列化工具結果，請清楚記錄格式（JSON 結構、欄位類型等）
返回結構化資料： JSON 或其他易於解析的格式最適合程式化處理
保持回應簡潔： 僅返回必要資料以最小化處理開銷

何時使用程式化呼叫

適合的使用案例：

處理只需要彙總或摘要的大型資料集
具有 3 個以上相依工具呼叫的多步驟工作流程
需要過濾、排序或轉換工具結果的操作
中間資料不應影響 Claude 推理的任務
跨多個項目的平行操作（例如，檢查 50 個端點）

較不理想的使用案例：

具有簡單回應的單一工具呼叫
需要立即使用者回饋的工具
程式碼執行開銷超過收益的非常快速的操作

效能最佳化

進行多個相關請求時重複使用容器以維持狀態
盡可能在單次程式碼執行中批次處理類似操作

疑難排解

常見問題

「工具不允許」錯誤

驗證您的工具定義是否包含 "allowed_callers": ["code_execution_20260120"]

容器過期

確保在容器閒置超時前回應工具呼叫（閒置 4.5 分鐘；30 天硬性上限）
監控回應中的 expires_at 欄位
考慮實作更快速的工具執行

工具結果未正確解析

確保您的工具返回 Claude 可以反序列化的字串資料
在工具說明中提供清晰的輸出格式文件

除錯技巧

記錄所有工具呼叫和結果以追蹤流程
檢查 caller 欄位以確認程式化調用
監控容器 ID以確保正確重複使用
獨立測試工具，然後再啟用程式化呼叫

程式化工具呼叫的運作原理

Claude 的訓練包含對程式碼的大量接觸，使其能夠有效地推理和串聯函數呼叫。當工具以程式碼執行環境中的可呼叫函數形式呈現時，Claude 可以利用這一優勢：

自然地推理工具組合： 像撰寫任何 Python 程式碼一樣自然地串聯操作並處理相依性
高效處理大型結果： 過濾大型工具輸出、僅提取相關資料，或在將摘要返回上下文視窗之前將中間結果寫入檔案
顯著降低延遲： 消除多步驟工作流程中每次工具呼叫之間重新取樣 Claude 的開銷

這種方法透過允許 Claude 以程式方式處理資料而非將所有內容載入對話上下文，實現了傳統工具使用無法實現的工作流程（例如處理超過 100 萬 token 的檔案）。

替代實作

程式化工具呼叫是一種可泛化的模式，可以在 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：最終回應

進階模式

使用迴圈進行批次處理

提前終止

條件式工具選擇

資料過濾

回應格式

程式化工具呼叫

工具結果處理

程式碼執行完成

錯誤處理

常見錯誤

工具呼叫期間容器過期

工具執行錯誤

限制與約束

功能不相容性

工具限制

訊息格式限制

速率限制

使用前驗證工具結果

Token 效率

使用量與定價

最佳實踐

工具設計

何時使用程式化呼叫

效能最佳化

疑難排解

常見問題

除錯技巧

程式化工具呼叫的運作原理

替代實作

客戶端直接執行

自行管理的沙箱執行

Anthropic 託管執行

資料保留

相關功能

`allowed_callers` 欄位

回應中的 `caller` 欄位