3.5 高级特性：程序化工具调用

3.5.1 什么是程序化工具调用 (Programmatic Tool Calling)？

在标准的工具使用模式中，Claude 扮演的是一个“调度员”：它输出指令，代码执行指令。虽然这种模式简单清晰，但在面对复杂任务时，它通过 HTTP 请求往返的“乒乓”效应会导致显著的延迟。

2025 年，Anthropic 引入了 程序化工具调用。这是一种范式转变：Claude 不再仅仅输出单一的 JSON 指令，而是能够编写并在安全的沙箱容器中执行 Python 代码脚本。这使得 Claude 能够通过代码逻辑（循环、判断、变量传递）一次性编排多个工具调用，甚至直接在沙箱中处理数据。

3.5.2 架构对比：打破“乒乓”效应

以下通过一个场景来对比两种模式：“获取系统中所有活跃用户的名单，并为每个人生成一份月度报表。”

传统模式 (Standard Tool Use)

1. Claude: get_active_users()

2. App: 返回 100 个用户的 JSON List（消耗大量 Token）。

3. Claude: generate_report(user_id=1)

4. App: 返回结果。

5. Claude: generate_report(user_id=2)

6. ... (重复100次)

由于上下文窗口 (Context Window) 限制和网络延迟，这种任务在传统模式下几乎不可行。

程序化模式 (Programmatic)

1. Claude: 生成并执行如下 Python 代码：

   users = tools.get_active_users() # 调用工具
   results = []
   
   # 在容器内进行逻辑处理，无需回传给 LLM 上下文
   for user in users:
       if user['status'] == 'active':
           rep = tools.generate_report(user_id=user['id'])
           results.append(rep)
           
   print(f"Generated {len(results)} reports.")

2. App/Container: 执行整段代码。

3. App: 仅返回最终的一句话结果。

优势总结：

• 极低延迟：将 100 次网络往返压缩为 1 次。

• 节省 Token：中间数据（如那 100 个用户的详细信息）在代码空间中流转，无需进入 LLM 的上下文窗口。

• 逻辑完备：支持 if-else、for 循环和异常处理。

3.5.3 配置与启用

要启用此功能，需要告知 Claude 哪些工具允许被代码调用。

allowed_callers 字段

在定义工具 Schema 时，新增 allowed_callers 属性：

tools = [
    {
        "name": "query_database",
        "description": "执行 SQL 查询",
        "input_schema": { ... },
        # 关键配置
        "allowed_callers": [
            "code_execution_20250825"  # 允许被代码容器调用
            # "direct"                 # 如果同时也允许标准模式调用
        ]
    }
]

容器环境

当 Claude 决定使用程序化工具时，它不仅会生成 tool_use，还会请求一个 code_execution 环境。

• 生命周期：每个 Session 默认创建一个新容器，并在闲置约 4.5 分钟后销毁。

• 状态保持：通过传递 container_id，可以让 Claude 在后续对话中访问之前定义的变量（如 pd.DataFrame）。

3.5.4 设计适合程序化调用的工具

程序化调用的工具设计理念与传统模式有所不同。

• 返回结构化数据：工具最好返回 JSON 对象、列表或 Pandas DataFrame 兼容的数据，方便代码处理。避免返回“自然语言描述”。

  • Bad: "张三的年龄是30岁。"

  • Good: {"name": "Zhang San", "age": 30}

• 原子化 (Atomic)：工具功能应尽量单一。组合逻辑交给 Claude 写代码去完成。

• 批量接口：虽然循环调用很快，但提供 batch_get_users([ids]) 这样的批量接口依然是性能优化的首选。

3.5.5 工具学习 (Tool Learning / Few-Shot)

对于极其复杂或非直观的工具，仅靠 description 可能不够。可以通过 Few-Shot Examples（少样本示例） 来“教会” Claude 如何编写正确的调用代码。

Anthropic 推荐使用 XML 格式提供示例：

<tool_examples>
    <example tool="data_visualizer">
        <task>为上季度的销售额绘制柱状图</task>
        <thinking>
            我需要先获取数据，然后使用 visualize 工具。注意数据格式必须是 List[Dict]。
        </thinking>
        <correct_usage>
            sales_data = tools.get_sales(quarter="Q3")
            # 数据预处理
            chart_data = [{"x": item["month"], "y": item["amount"]} for item in sales_data]
            tools.visualize(
                type="bar", 
                data=chart_data, 
                title="Q3 Sales"
            )
        </correct_usage>
    </example>
</tool_examples>

将这部分内容包含在 system prompt 中，能显著提高一次成功率。

3.5.6 限制与注意事项

尽管功能强大，但目前仍存在边界：

1. 不支持 Web Search：目前 web_search 等服务端工具无法在代码容器内直接调用。

2. 严格的响应格式：当处理程序化调用的结果时，必须严格遵守 tool_result 格式，任何多余的文本内容 (Text content) 都可能导致解析错误。

3. 安全性：虽然运行在沙箱中，但让 AI 写代码并执行总是伴随风险。建议对代码容器进行网络隔离，仅允许其访问白名单内的 API。

3.5.7 最佳实践清单

维度	建议
工具粒度	保持工具简单、原子化。避免“万能工具”。
数据格式	始终针对“机器读取”而非“人类阅读”优化工具返回值。
错误处理	在工具内部捕获异常并返回清晰的错误 JSON，让 Claude 的代码能 try-catch。
监控	记录 Claude 生成的所有代码，这对于调试和安全审计至关重要。

---

当工具数量增长到数百个时，如何让 Claude 找到正确的工具？需要“工具搜索”。

➡️ 工具搜索与大规模管理