工具基础设施

程序化工具调用

了解如何使用程序化工具调用来减少延迟和令牌消耗

程序化工具调用允许 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.

模型兼容性

有关模型兼容性和工具版本详情，请参阅工具参考。程序化工具调用可通过 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 的情况下串行或循环调用工具来节省令牌和延迟
条件逻辑： 基于中间工具结果做出决策

自定义工具被转换为异步 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`	未提供必需的 beta 标头（仅限 Bedrock 和 Vertex AI；程序化工具调用在第一方 Claude API 上是 GA）	将所需的 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}]"
    }
  ]
}

此限制仅在响应程序化（代码执行）工具调用时适用。对于常规客户端工具调用，您可以在工具结果后包含文本内容。

速率限制

程序化工具调用受与常规工具调用相同的速率限制。来自代码执行的每个工具调用都计为单独的调用。

在使用前验证工具结果

在实现将以编程方式调用的用户定义工具时：

工具结果作为字符串返回： 它们可以包含任何内容，包括代码片段或可执行命令，这些可能会被执行环境处理。
验证外部工具结果： 如果您的工具返回来自外部源的数据或接受用户输入，请注意如果输出将被解释或作为代码执行，代码注入风险。

令牌效率

程序化工具调用可以显著降低令牌消耗：

来自程序化调用的工具结果不会添加到 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 和数据保留。

程序化工具调用

了解如何使用程序化工具调用来减少延迟和令牌消耗

有关程序化工具调用所解决的推理和上下文成本的更深入了解，请参阅高级工具使用。

此功能需要启用代码执行工具。

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 的情况下串行或循环调用工具来节省令牌和延迟
条件逻辑： 基于中间工具结果做出决策

为了清晰起见，本文档中的代码示例中省略了异步包装。

核心概念

`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 以在请求之间维护状态

示例工作流

以下是完整的程序化工具调用流程的工作方式：

步骤 1：初始请求

发送包含代码执行和允许程序化调用的工具的请求。要启用程序化调用，请将 allowed_callers 字段添加到您的工具定义中。

步骤 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`	未提供必需的 beta 标头（仅限 Bedrock 和 Vertex AI；程序化工具调用在第一方 Claude API 上是 GA）	将所需的 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 连接器提供的工具

消息格式限制

在响应程序化工具调用时，有严格的格式要求：

无效 - 响应程序化工具调用时不能包含文本：

{
  "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 以确保正确重用
独立测试工具 在启用程序化调用之前

为什么程序化工具调用有效

自然地推理工具组合： 链接操作并处理依赖关系，就像编写任何 Python 代码一样自然
高效处理大型结果： 过滤大型工具输出，仅提取相关数据，或在返回摘要到上下文窗口之前将中间结果写入文件
显著降低延迟： 消除在多步工作流中每个工具调用之间重新采样 Claude 的开销

替代实现

程序化工具调用是一个可以在 Anthropic 的托管代码执行之外实现的通用模式。以下是方法概述：

客户端直接执行

为 Claude 提供代码执行工具，并描述该环境中可用的函数。当 Claude 使用代码调用工具时，您的应用程序在定义了这些函数的本地执行它。

优点：

使用最少的重新架构简单实现
完全控制环境和说明

缺点：

在沙箱外执行不受信任的代码
工具调用可能是代码注入的向量

何时使用： 您的应用程序可以安全地执行任意代码，您想要一个简单的解决方案，并且 Anthropic 的托管产品不适合您的需求。

自管理沙箱执行

优点：

在您自己的基础设施上安全的程序化工具调用
完全控制执行环境

缺点：

复杂的构建和维护
需要管理基础设施和进程间通信

何时使用： 安全至关重要，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 字段

容器生命周期

示例工作流

步骤 1：初始请求

步骤 2：带有工具调用的 API 响应

步骤 3：提供工具结果

步骤 4：下一个工具调用或完成

步骤 5：最终响应

高级模式

使用循环进行批处理

早期终止

条件工具选择

数据过滤

响应格式

程序化工具调用

工具结果处理

代码执行完成

错误处理

常见错误

工具调用期间容器过期

工具执行错误

约束和限制

功能不兼容性

工具限制

消息格式限制

速率限制

在使用前验证工具结果

`allowed_callers` 字段

响应中的 `caller` 字段

`allowed_callers` 字段

响应中的 `caller` 字段