编程式工具调用：容器内执行

标准的 Tool Use 需要 API 往返——Claude 说"我要调用工具"，你执行工具，把结果返回给 Claude。Programmatic Tool Calling 允许在容器化环境中直接执行代码，减少往返延迟。

你将学到什么

标准 Tool Use 的延迟问题
Code Execution Tool 的工作方式
容器化代码执行的安全模型
适用场景和最佳实践

标准 Tool Use 的痛点

每次工具调用需要 3 步：

Client → API: "调用 calculate(2+3)"
API → Client: tool_use block
Client: 执行计算，得到结果 5
Client → API: tool_result = 5
API → Client: "结果是 5"

每次往返增加网络延迟。如果一个任务需要 5 次工具调用，延迟会叠加。

Code Execution Tool

Claude 的 Code Execution Tool 让 Claude 在沙箱中直接写代码并执行，无需外部往返。

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    tools=[{
        "type": "code_execution_20250522",
        "name": "code_execution",
    }],
    messages=[{
        "role": "user",
        "content": "计算斐波那契数列前 20 项，并画一个增长趋势图"
    }]
)

# Claude 会自动写 Python 代码并在沙箱中执行
# 返回结果包含代码、输出和生成的图片
for block in response.content:
    if block.type == "code_execution_result":
        print("执行结果:", block.output)
    elif block.type == "image":
        # 保存生成的图片
        print("生成了图表")

沙箱安全模型

Code Execution 在安全沙箱中运行：

隔离环境：每次执行在独立容器中
无网络：代码不能访问外部网络
时间限制：执行时间有上限
资源限制：内存和 CPU 受控
预装库：常见的数据分析库（pandas、matplotlib、numpy 等）

实际应用场景

数据分析

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=8192,
    tools=[{"type": "code_execution_20250522", "name": "code_execution"}],
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "分析这个 CSV 数据，找出销售趋势"},
            {"type": "document", "source": {
                "type": "base64",
                "media_type": "text/csv",
                "data": csv_base64
            }}
        ]
    }]
)

数学计算和可视化

Claude 可以编写 matplotlib 代码生成图表，并直接返回图片。这比让 Claude 口头描述数据趋势要直观得多。

代码验证

让 Claude 写代码后立即执行验证，确保代码正确。

与标准 Tool Use 的对比

对比项	标准 Tool Use	Code Execution
延迟	每次工具调用需要 API 往返	在容器内直接执行
灵活性	预定义工具	任意 Python 代码
网络访问	取决于你的实现	无网络（沙箱）
安全性	你负责安全	平台负责隔离
适用场景	调用外部 API/数据库	计算、分析、可视化

组合使用

最强大的模式是组合使用两者：

tools = [
    # Code Execution：计算和可视化
    {"type": "code_execution_20250522", "name": "code_execution"},
    # 标准 Tool：外部 API
    {
        "name": "query_database",
        "description": "查询数据库获取数据",
        "input_schema": {
            "type": "object",
            "properties": {
                "sql": {"type": "string"}
            }
        }
    }
]

# Claude 会先调用 query_database 获取数据
# 然后用 code_execution 分析和可视化

实战练习

Tip: 体验 Code Execution 的即时执行能力。

让 Claude 用 Code Execution 做一个数学计算任务
上传一个 CSV 文件，让 Claude 分析并生成图表
对比标准 Tool Use 和 Code Execution 的延迟差异

关键要点

Note: 本文核心总结

Code Execution 在沙箱中直接执行 Python，无需 API 往返
沙箱是安全的：无网络、有资源限制、独立容器
最适合计算、数据分析和可视化场景
与标准 Tool Use 组合使用效果最佳