工具基础设施

编程式工具调用

了解如何让 Claude 在代码执行容器中以编程方式调用您的工具。

编程式工具调用允许 Claude 在代码执行容器中编写代码以编程方式调用您的工具，而不是每次工具调用都需要通过模型进行往返通信。这减少了多工具工作流的延迟，并通过允许 Claude 在数据到达模型上下文窗口之前对其进行过滤或处理来降低 token 消耗。

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

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

模型兼容性

编程式工具调用可在以下模型上使用：

模型	工具版本
Claude Opus 4.6 (`claude-opus-4-6`)	`code_execution_20250825`
Claude Sonnet 4.6 (`claude-sonnet-4-6`)	`code_execution_20250825`
Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`)	`code_execution_20250825`
Claude Opus 4.5 (`claude-opus-4-5-20251101`)	`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 "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_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 上下文之前进行过滤或聚合
多步骤工作流：通过串行或循环调用工具来节省 token 和延迟，无需在工具调用之间对 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.messages.create(
    model="claude-opus-4-6",
    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.messages.create(
    model="claude-opus-4-6",
    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 可以编写高效处理多个项目的代码：

# 为清晰起见省略了异步包装器
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)

# 以编程方式处理结果
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 可以在满足成功条件后立即停止处理：

# 为清晰起见省略了异步包装器
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  # 提前停止，不检查剩余的

条件工具选择

# 为清晰起见省略了异步包装器
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)

数据过滤

# 为清晰起见省略了异步包装器
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:]:  # 仅返回最后 10 个错误
    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`	未提供所需的 beta 头	在请求中添加所需的 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 个端点）

不太理想的用例：

具有简单响应的单个工具调用
需要即时用户反馈的工具
代码执行开销会超过收益的非常快速的操作

性能优化

在进行多个相关请求时重用容器以保持状态
尽可能在单次代码执行中批量处理类似操作

故障排除

常见问题

"Tool not allowed" 错误

验证您的工具定义包含 "allowed_callers": ["code_execution_20250825"]

容器过期

确保在容器生命周期内（约 4.5 分钟）响应工具调用
监控响应中的 expires_at 字段
考虑实现更快的工具执行

工具结果未正确解析

确保您的工具返回 Claude 可以反序列化的字符串数据
在工具描述中提供清晰的输出格式文档

调试技巧

记录所有工具调用和结果以跟踪流程
检查 caller 字段以确认编程式调用
监控容器 ID 以确保正确重用
在启用编程式调用之前独立测试工具

编程式工具调用为何有效

Claude 的训练包含大量代码接触，使其能够有效地推理和链接函数调用。当工具作为代码执行环境中的可调用函数呈现时，Claude 可以利用这一优势来：

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

这种方法使传统工具使用不切实际的工作流成为可能——例如处理超过 1M token 的文件——通过允许 Claude 以编程方式处理数据，而不是将所有内容加载到对话上下文中。

替代实现

编程式工具调用是一种可推广的模式，可以在 Anthropic 托管的代码执行之外实现。以下是各种方法的概述：

客户端直接执行

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

优势：

实现简单，无需大量重新架构
完全控制环境和指令

劣势：

在沙盒外执行不受信任的代码
工具调用可能成为代码注入的载体

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

自管理沙盒执行

从 Claude 的角度来看方法相同，但代码在具有安全限制的沙盒容器中运行（例如，无网络出口）。如果您的工具需要外部资源，您需要一个在沙盒外执行工具调用的协议。

优势：

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

劣势：

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

适用场景： 安全性至关重要且 Anthropic 的托管解决方案不符合您的要求。

Anthropic 托管执行

Anthropic 的编程式工具调用是沙盒执行的托管版本，具有为 Claude 调优的固定 Python 环境。Anthropic 处理容器管理、代码执行和安全的工具调用通信。

优势：

默认安全可靠
配置最少即可轻松启用
环境和指令针对 Claude 进行了优化

如果您使用 Claude API，我们建议使用 Anthropic 的托管解决方案。

编程式工具调用

了解如何让 Claude 在代码执行容器中以编程方式调用您的工具。

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

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

模型兼容性

编程式工具调用可在以下模型上使用：

模型	工具版本
Claude Opus 4.6 (`claude-opus-4-6`)	`code_execution_20250825`
Claude Sonnet 4.6 (`claude-sonnet-4-6`)	`code_execution_20250825`
Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`)	`code_execution_20250825`
Claude Opus 4.5 (`claude-opus-4-5-20251101`)	`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 "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_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 上下文之前进行过滤或聚合
多步骤工作流：通过串行或循环调用工具来节省 token 和延迟，无需在工具调用之间对 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"] - 可直接调用也可从代码执行中调用

我们建议为每个工具选择 ["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 以在请求之间保持状态

示例工作流

以下是完整的编程式工具调用流程：

步骤 1：初始请求

发送包含代码执行和允许编程式调用的工具的请求。要启用编程式调用，请在工具定义中添加 allowed_callers 字段。

response = client.messages.create(
    model="claude-opus-4-6",
    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.messages.create(
    model="claude-opus-4-6",
    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 可以编写高效处理多个项目的代码：

# 为清晰起见省略了异步包装器
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)

# 以编程方式处理结果
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 可以在满足成功条件后立即停止处理：

# 为清晰起见省略了异步包装器
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  # 提前停止，不检查剩余的

条件工具选择

# 为清晰起见省略了异步包装器
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)

数据过滤

# 为清晰起见省略了异步包装器
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:]:  # 仅返回最后 10 个错误
    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`	未提供所需的 beta 头	在请求中添加所需的 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}]"}
  ]
}

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

速率限制

编程式工具调用受与常规工具调用相同的速率限制。代码执行中的每个工具调用都算作一次单独的调用。

使用前验证工具结果

实现将被编程式调用的自定义工具时：

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

Token 效率

编程式工具调用可以显著减少 token 消耗：

编程式调用的工具结果不会添加到 Claude 的上下文中 - 只有最终的代码输出会
中间处理在代码中进行 - 过滤、聚合等不消耗模型 token
一次代码执行中的多个工具调用 - 与单独的模型轮次相比减少了开销

例如，直接调用 10 个工具使用的 token 大约是以编程方式调用它们并返回摘要的 10 倍。

使用和定价

编程式工具调用使用与代码执行相同的定价。详情请参阅代码执行定价。

编程式工具调用的 token 计算：编程式调用的工具结果不计入您的输入/输出 token 使用量。只有最终的代码执行结果和 Claude 的响应才计入。

最佳实践

工具设计

提供详细的输出描述：由于 Claude 在代码中反序列化工具结果，请清楚地记录格式（JSON 结构、字段类型等）
返回结构化数据：JSON 或其他易于解析的格式最适合编程式处理
保持响应简洁：仅返回必要的数据以最小化处理开销

何时使用编程式调用

适合的用例：

处理大型数据集，您只需要聚合或摘要
包含 3 个以上依赖工具调用的多步骤工作流
需要对工具结果进行过滤、排序或转换的操作
中间数据不应影响 Claude 推理的任务
跨多个项目的并行操作（例如，检查 50 个端点）

不太理想的用例：

具有简单响应的单个工具调用
需要即时用户反馈的工具
代码执行开销会超过收益的非常快速的操作

性能优化

在进行多个相关请求时重用容器以保持状态
尽可能在单次代码执行中批量处理类似操作

故障排除

常见问题

"Tool not allowed" 错误

验证您的工具定义包含 "allowed_callers": ["code_execution_20250825"]

容器过期

确保在容器生命周期内（约 4.5 分钟）响应工具调用
监控响应中的 expires_at 字段
考虑实现更快的工具执行

工具结果未正确解析

确保您的工具返回 Claude 可以反序列化的字符串数据
在工具描述中提供清晰的输出格式文档

调试技巧

记录所有工具调用和结果以跟踪流程
检查 caller 字段以确认编程式调用
监控容器 ID 以确保正确重用
在启用编程式调用之前独立测试工具

编程式工具调用为何有效

Claude 的训练包含大量代码接触，使其能够有效地推理和链接函数调用。当工具作为代码执行环境中的可调用函数呈现时，Claude 可以利用这一优势来：

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

替代实现

编程式工具调用是一种可推广的模式，可以在 Anthropic 托管的代码执行之外实现。以下是各种方法的概述：

客户端直接执行

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

优势：

实现简单，无需大量重新架构
完全控制环境和指令

劣势：

在沙盒外执行不受信任的代码
工具调用可能成为代码注入的载体

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

自管理沙盒执行

优势：

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

劣势：

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

适用场景： 安全性至关重要且 Anthropic 的托管解决方案不符合您的要求。

Anthropic 托管执行

Anthropic 的编程式工具调用是沙盒执行的托管版本，具有为 Claude 调优的固定 Python 环境。Anthropic 处理容器管理、代码执行和安全的工具调用通信。

优势：

默认安全可靠
配置最少即可轻松启用
环境和指令针对 Claude 进行了优化

如果您使用 Claude API，我们建议使用 Anthropic 的托管解决方案。

模型兼容性

快速开始

编程式工具调用的工作原理

核心概念

allowed_callers 字段

响应中的 caller 字段

容器生命周期

示例工作流

步骤 1：初始请求

步骤 2：API 响应包含工具调用

步骤 3：提供工具结果

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

步骤 5：最终响应

高级模式

使用循环进行批量处理

提前终止

条件工具选择

数据过滤

响应格式

编程式工具调用

工具结果处理

代码执行完成

错误处理

常见错误

工具调用期间容器过期

工具执行错误

约束和限制

功能不兼容性

工具限制

消息格式限制

速率限制

使用前验证工具结果

Token 效率

使用和定价

最佳实践

工具设计

何时使用编程式调用

性能优化

故障排除

常见问题

调试技巧

编程式工具调用为何有效

替代实现

客户端直接执行

自管理沙盒执行

Anthropic 托管执行

相关功能

模型兼容性

快速开始

编程式工具调用的工作原理

核心概念

allowed_callers 字段

响应中的 caller 字段

容器生命周期

示例工作流

步骤 1：初始请求

步骤 2：API 响应包含工具调用

步骤 3：提供工具结果

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

步骤 5：最终响应

高级模式

使用循环进行批量处理

提前终止

条件工具选择

数据过滤

响应格式

编程式工具调用

工具结果处理

代码执行完成

错误处理

常见错误

工具调用期间容器过期

工具执行错误

约束和限制

功能不兼容性

工具限制

消息格式限制

速率限制

使用前验证工具结果

Token 效率

`allowed_callers` 字段

响应中的 `caller` 字段

`allowed_callers` 字段

响应中的 `caller` 字段