程式化工具呼叫

程式化工具呼叫允許 Claude 在程式碼執行容器中編寫以程式方式呼叫工具的程式碼，而不需要為每次工具呼叫進行往返模型。這可以減少多工具工作流程的延遲，並通過允許 Claude 在資料到達模型的上下文視窗之前過濾或處理資料來降低代幣消耗。在BrowseComp和DeepSearchQA等代理搜尋基準上，這些基準測試多步驟網路研究和複雜資訊檢索，在基本搜尋工具之上添加程式化工具呼叫是完全解鎖代理效能的關鍵因素。

差異在實際工作流程中迅速複合。考慮檢查 20 名員工的預算合規性：傳統方法需要 20 次單獨的模型往返，沿途將數千個費用行項目拉入上下文。使用程式化工具呼叫，單個指令碼執行所有 20 次查詢，過濾結果，並僅返回超過限額的員工，將 Claude 需要推理的內容從數百千位元組縮小到幾行。

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

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

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

模型相容性

程式化工具呼叫需要 code_execution_20260120，以下模型支援此功能：

模型
Claude Opus 4.7 (`claude-opus-4-7`)
Claude Opus 4.6 (`claude-opus-4-6`)
Claude Sonnet 4.6 (`claude-sonnet-4-6`)
Claude Opus 4.5 (`claude-opus-4-5-20251101`)
Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`)

如需完整的程式碼執行工具版本矩陣，請參閱程式碼執行工具模型相容性表。程式化工具呼叫可通過 Claude API 和 Microsoft Foundry 使用。

快速開始

以下是一個簡單範例，其中 Claude 以程式方式多次查詢資料庫並聚合結果：

程式化工具呼叫的運作方式

當您配置工具可從程式碼執行呼叫，且 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_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 之前以程式方式處理大型結果集
只返回彙總結論而不是原始資料，節省代幣

早期終止

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`	未提供必需的測試版標頭（僅限 Bedrock 和 Vertex AI；程式化工具呼叫在第一方 Claude API 上為 GA）	將必需的測試版標頭新增到您的請求中

工具呼叫期間容器過期

如果您的工具花費太長時間來回應，程式碼執行會收到 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 的上下文中 - 只有最終程式碼輸出會
中間處理在程式碼中進行 - 篩選、彙總等不會消耗模型代幣
一個程式碼執行中的多個工具呼叫 - 相比於單獨的模型轉換減少開銷

例如，直接呼叫 10 個工具使用的代幣大約是以程式方式呼叫它們並返回摘要的 10 倍。

使用和定價

程式化工具呼叫使用與程式碼執行相同的定價。有關詳細資訊，請參閱程式碼執行定價。

程式化工具呼叫的代幣計數：來自程式化呼叫的工具結果不計入您的輸入/輸出代幣使用量。只有最終程式碼執行結果和 Claude 的回應計算。

最佳實踐

工具設計

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

何時使用程式化呼叫

良好的使用案例：

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

不太理想的使用案例：

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

效能最佳化

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

疑難排解

常見問題

「工具不允許」錯誤

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

容器過期

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

工具結果未正確解析

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

除錯提示

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

為什麼程式化工具呼叫有效

Claude 的訓練包括對程式碼的廣泛接觸，使其在推理和鏈接函式呼叫方面有效。當工具在程式碼執行環境中呈現為可呼叫函式時，Claude 可以利用此優勢來：

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

此方法啟用了使用傳統工具使用不切實際的工作流程（例如處理超過 1M 代幣的檔案），允許 Claude 以程式方式處理資料，而不是將所有內容載入到對話上下文中。

替代實現

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

進階模式

使用迴圈進行批次處理

早期終止

條件工具選擇

資料篩選

回應格式

程式化工具呼叫

工具結果處理

程式碼執行完成

錯誤處理

常見錯誤

工具呼叫期間容器過期

工具執行錯誤

限制和限制

功能不相容性

工具限制

訊息格式限制

速率限制

在使用前驗證工具結果

代幣效率

使用和定價

最佳實踐

工具設計

何時使用程式化呼叫

效能最佳化

疑難排解

常見問題

除錯提示

為什麼程式化工具呼叫有效

替代實現

用戶端直接執行

自我管理的沙箱執行

Anthropic 託管執行

資料保留

相關功能

`allowed_callers` 欄位

回應中的 `caller` 欄位