# 工具调用中，模型只提议，执行权在你的代码

> Anthropic、OpenAI 和 Google 描述的是同一套契约，FDE 据此就能找准安全团队关心的检查点。

原文: https://fdetimes.net/zh/guides/tool-calling-model-proposes-code-executes/

演示进行得很顺利。客服智能体收到一条消息：“我的订单颜色发错了，请给我退款”，随后回复退款申请已创建。客户的运营负责人皱起眉头，问出了每个 FDE 迟早都会听到的问题：“所以这个 AI 会自己进我们的支付系统？”

正确答案是：不会。前线部署工程师（FDE）必须能讲清楚为什么。如果只说一句“模型调用了 API”，客户脑子里浮现的会是一台机器在他们的系统里随意按按钮。真正理解这套机制，就能准确指出检查点在哪里，安全方面的讨论也会走向完全不同的方向。

凡是涉及智能体的部署，都以这项能力为基础。误解工具调用的工程师写出的集成很松散；理解它的工程师，能设计出安全团队和智能体都信得过的工具层。

## 模型不按任何按钮

Anthropic 的文档把这份契约说得很直白：模型从不自行执行任何操作。它输出一个结构化请求，由你的代码执行操作，结果再回到对话中。

Google 对 Gemini API 的说法几乎一模一样：模型本身不运行函数，由应用提取函数名和参数并执行。

OpenAI 则一步步描述了同样的流程：应用收到一个工具调用，以该调用中的输入运行应用侧代码，再发送第二个请求，附上输出结果。三家主要厂商，三套不同的 API，同一种架构。模型只是提议者，执行权属于你的代码。

有一个例外值得了解。对 web_search、code_execution 等部分工具，Anthropic 在自己的服务器上执行，你无需为它们构造 tool_result 块。而凡是触及客户系统的工具，无论是数据库、CRM 还是支付网关，都是由你定义、由你的代码运行的。

**要点:** 模型写请求，你的代码决定是否照办。

## 每次工具调用都是一次往返

Anthropic 工程团队的一篇文章把工具称为一种新型软件：确定性系统与非确定性智能体之间的契约。由于模型无法运行你的代码，每次工具调用都是一次往返：模型提出请求，你执行，你回报结果，模型继续。

遇到你定义的工具时，API 会返回一个 `tool_use` 块，其中包含工具名和 JSON 参数；你在下一个请求中发送 `tool_result`。

实际写出来，这个循环非常短：只要 `stop_reason == "tool_use"`，就执行工具并继续对话；遇到其他任何停止原因就退出。下面是针对上文退款场景的一个假设示例，用 Python 和 Anthropic 的 SDK 编写：

```python
TOOLS = [{
    "name": "issue_refund",
    "description": "为已送达的订单创建一个待审批的退款申请。",
    "input_schema": {
        "type": "object",
        "properties": {
            "order_id": {"type": "string"},
            "amount": {"type": "number"},
            "reason": {"type": "string",
                       "enum": ["damaged", "late", "wrong_item"]}
        },
        "required": ["order_id", "amount", "reason"]
    }
}]

def run_tool(name, args):
    if name != "issue_refund":
        return f"工具 '{name}' 不存在。可用工具：issue_refund。"
    order = db.get_order(args["order_id"])
    if order is None:
        return (f"找不到订单 {args['order_id']}。"
                "请再向客户确认订单号，格式如 DH-xxxxxx。")
    if args["amount"] > order.total:
        return (f"金额 {args['amount']} 超过订单总额 {order.total}。"
                f"请提议一个 <= {order.total} 的金额。")
    ticket = refunds.create_pending(order.id, args["amount"], args["reason"])
    return f"已创建申请 {ticket.id}，状态：等待工作人员审批。"

messages = [{"role": "user",
             "content": "订单 DH-104233 收到的颜色不对，请给我退款。"}]

for _ in range(8):  # 限制轮数，避免智能体无休止地运行
    resp = client.messages.create(model=MODEL, max_tokens=1024,
                                  tools=TOOLS, messages=messages)
    messages.append({"role": "assistant", "content": resp.content})
    if resp.stop_reason != "tool_use":
        break
    results = [{"type": "tool_result", "tool_use_id": b.id,
                "content": run_tool(b.name, b.input)}
               for b in resp.content if b.type == "tool_use"]
    messages.append({"role": "user", "content": results})
```

（示例中，工具创建的是*待审批*的退款申请；错误信息会告诉智能体订单不存在，应向客户索要 DH-xxxxxx 格式的订单号，或者金额超过订单总额，应提议一个不超过总额的金额。循环处的注释意为：限制轮数，绝不让智能体无休止地运行。）

现在换成那位运营负责人的视角读这段代码。模型只提供三个值：订单号、金额和原因。查找订单、比较金额与订单总额、创建*待审批*的申请而不是立即打款，这些决定全都在 `run_tool` 里做出。由你编写，由你测试，也由你负责。

## 三层防线，缺一不可

第一层是 schema。OpenAI 建议利用枚举和对象结构，让非法状态在 schema 层面就无法表达。上例中的 `reason` 字段只接受三个值，智能体没法编出“老客户”这样的理由。

OpenAI 还提供严格模式：在 OpenAI 的函数定义中把 `strict` 设为 `true`，函数调用就会可靠地遵循 schema，而不是尽力而为。

如果使用的是其他 API，请查阅其文档中的对应机制。

但符合 schema 的 JSON 在业务上仍可能是错的。schema 不知道订单 DH-104233 的总额，也不知道这位客户上周刚退过款。所以第二层，即代码中的校验，即使开了严格模式也不能省。

第三层最容易被忽视：错误信息。Anthropic 工程团队建议，工具的错误响应应具体说明需要改进什么，而不是返回含义不明的错误码或堆栈信息。“请提议一个 &lt;= 450000 的金额”能让智能体在下一轮自行纠正；`ValueError at line 42` 只会让它瞎猜。

## 用到自己的项目里

先列出智能体需要执行的所有操作，分成只读和写入两组。对写入组，在客户需求调研阶段问清哪些操作需要人工审批，再把这些工具设计成返回“待审批”状态，就像上面的示例那样，而不是直接执行。

接着，把 schema 写得尽量窄。值域固定的字段一律用枚举，只把真正需要的字段标为必填。然后编写 `run_tool`，让每个错误分支都返回一句话，告诉智能体下一步该怎么做。

最后，留意结果的大小。一个返回 5,000 行日志的查询工具会很快塞满上下文。Anthropic 建议对这类响应组合使用分页、范围选择、过滤和截断；截断时，再加一行提示，告诉智能体如何请求下一页。

## 导致部署失败的错误

最常见的错误，是以为把规则写进系统提示词，模型就“知道”了。提示词是建议，代码才是法律。凡是涉及资金、访问权限或个人数据的约束，都必须放在 `run_tool` 里。

第二个是没有上限的循环。如果工具一直报错、智能体一直重试，`while True` 会无止境地消耗 token。设置轮数上限、记录每一次调用，代价很小，远比半夜出事故划算。

第三个是把原始异常直接丢进 `tool_result`。这些信息对智能体毫无用处，还可能把文件路径或客户数据库的结构泄露到对话里。

如果目标是 FDE 岗位，求职时要把这项能力展示出来。岗位描述要求有 LLM 集成或智能体开发经验时，正好借此详细介绍自己搭建过的工具层。简历上不要只写“LLM 集成”。

要写清楚校验放在哪里、哪些工具需要人工审批、结果如何分页。面试官一眼就能看出，你清楚执行权握在哪一方手里。

下次客户再问“这个 AI 能自己做这件事吗？”，别急着安抚。打开 `run_tool`，带他们逐行看那些决定什么可以发生的代码。

**本周动手试试:**

- 把本文的循环改写成一个读取公司真实数据的工具，比如订单或工单查询，并加上轮数上限。
- 检查一个现有工具，改写每条错误信息，让它回答一个问题：智能体应该用什么参数重新调用？
- 在简历上加一行，描述你设计的工具层：校验、分页，以及哪些操作需要人工审批。

## 信源

- [How tool use works](https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works)

- [Function calling with the Gemini API | Google AI for Developers](https://ai.google.dev/gemini-api/docs/function-calling)

- [Function calling](https://developers.openai.com/api/docs/guides/function-calling)

- [Writing effective tools for agents — with agents](https://www.anthropic.com/engineering/writing-tools-for-agents)
