结论先行:Function Calling 不是模型替你执行函数,而是模型输出一个结构化的"我想调用某工具及参数 JSON",真正的执行、鉴权、审计全部发生在你的代码里。理解这一点,工具调用的可靠性问题就退化成一个普通的后端工程问题。

原理:工具定义进 Prompt,调用意图出模型

工作原理分两步。第一步,你把工具列表(名称、描述、参数的 JSON Schema)随请求发给模型,它们会成为上下文的一部分——注意这也意味着每个工具定义都在消耗上下文,挂五十个工具和挂五个工具,模型的选择难度完全不同。第二步,模型判断需要外部能力时,不输出自然语言,而是返回结构化的 tool_calls——一个工具名加一串参数 JSON。

关键认知:模型生成的参数 JSON 不可信。它是"建议",你要像校验用户输入一样校验它:Schema 校验(类型、必填、格式)、业务校验(这个用户有没有权限操作这个 ID)、参数合法性(日期格式、数值范围)。把模型当成一个"会读文档、会填参数表单的调用方",你的工具就是它的下游 RPC——用什么标准设计下游接口,就用什么标准设计工具。

还有一类容易忽略的失败:模型该调工具时没调。原因通常是工具描述与用户话术对不上——用户问"东西走到哪了",工具描述只写"运单状态查询",模型没建立起两者的联系。在描述里补上用户可能使用的说法(“走到哪了"“到哪了"“什么状态”),是提高触发率最便宜的手段,这类问题在换更贵的模型上浪费过很多预算。

标准循环:一个 Agent 的最小内核

所有 Function Calling 应用共享同一个循环:

tools = [{
    "type": "function",
    "function": {
        "name": "get_order",
        "description": "按运单号查询运单状态、司机与费用信息",
        "parameters": {
            "type": "object",
            "properties": {
                "order_no": {"type": "string", "description": "运单号,如 FY20251209001"}
            },
            "required": ["order_no"]
        }
    }
}]

messages = [{"role": "user", "content": "帮我查下运单 FY20251209001 到哪了"}]
for _ in range(MAX_ROUNDS):                      # 熔断:防止无限循环
    resp = client.chat.completions.create(
        model=MODEL, messages=messages, tools=tools)
    msg = resp.choices[0].message
    messages.append(msg)                         # tool_calls 消息也要进历史
    if not msg.tool_calls:                       # 模型不再调工具,直接给答案
        break
    for tc in msg.tool_calls:
        args = json.loads(tc.function.arguments)
        result = dispatch(tc.function.name, validate(args))   # 真正执行的是你的代码
        messages.append({"role": "tool", "tool_call_id": tc.id,
                         "content": json.dumps(result, ensure_ascii=False)})

循环里有两个容易漏掉的细节:模型返回的 tool_calls 消息必须原样 append 回历史(messages.append(msg) 这行经常被误删),否则下一轮请求里工具调用与工具结果对不上号,接口直接报错;退出循环只有两条路——模型不再请求工具,或轮数熔断触发。调试这类循环的方法很朴素:把每轮发出的 messages 完整打印出来,人眼过一遍,八成问题一眼可见。这个循环就是 Agent 的最小内核,后面几篇讲的 ReAct、上下文管理、评估,都是在给它加工程化能力。

四个工程要点

  1. 错误回传而不是抛异常。工具执行失败时,把错误信息作为 tool result 返回给模型,它会尝试修正参数重试;直接抛异常整轮就废了。
  2. 最大轮数熔断。模型可能陷入"调用-失败-再调用"的循环,MAX_ROUNDS 是必要的保险丝,超限后降级为转人工,而不是让循环烧 token。阈值按正常任务的最大轮数上浮一点设置,设太紧会把合法的多步任务拦腰截断。
  3. 返回值为模型裁剪。不要把一个 30 字段的数据库实体原样塞回去,只返回与当前问题相关的字段,否则上下文很快被污染。裁剪的基准不是"接口返回了什么”,而是"回答当前问题需要什么”:状态、位置、时间、金额这些决策相关字段留下,创建人、备注列表、审计字段去掉。
  4. 并行调用按幂等处理。模型可能一次返回多个 tool_calls,执行顺序和重试语义要按普通分布式调用的标准来设计:读操作可以并行,写操作想清楚失败一半怎么办。写操作要么设计成幂等(带业务单号去重),要么串行执行——模型不会替你保证幂等,这是服务端的责任。

错误回传:错误写法与正确写法

错误回传是最容易写错的一处。错误信息不是给运维看的堆栈,是给模型看的修正提示:

# 错误写法一:异常直接抛出,整轮对话作废
args = json.loads(tc.function.arguments)
result = dispatch(tc.function.name, args)        # 抛异常,循环中断,用户看到 500

# 错误写法二:回传堆栈,模型不知道该怎么改
messages.append({"role": "tool", "content": traceback.format_exc()})
# 正确写法:错误码 + 一句话说明 + 下一步建议,模型读完就知道怎么修正
try:
    result = dispatch(tc.function.name, validate(args))
except ToolError as e:
    result = {"error": e.code,                   # 机器可读的错误码,便于日志统计
              "message": e.human_message,        # 人能看懂的一句话
              "hint": e.next_action}             # 模型下一步该做什么
messages.append({"role": "tool", "tool_call_id": tc.id,
                 "content": json.dumps(result, ensure_ascii=False)})

hint 是三者里最关键的字段。“order_no 格式错误"模型可能原样重试三次,“运单号应为 FY 开头的 13 位数字,手机号查询请改用 search_order_by_customer"能让它一次改对。

安全与审计:执行权永远在你手里

参数校验要过三道关,每道关的失败处理不同:

校验层校验内容失败处理
Schema 校验类型、必填、枚举、格式错误回传,让模型重填参数
权限校验当前用户能否操作该对象直接拒绝,不回传给模型重试
业务规则金额上限、时间窗、状态机约束拒绝并给出可读原因

注意权限校验失败不能回传给模型——模型会换参数绕过去。权限层的拒绝是终态,直接终止本轮并记录审计日志。每一次工具调用(谁、在哪个会话里、调了什么工具、传了什么参数、返回什么)都应落审计日志,这不是合规选修课,是排查"模型为什么这么干"的唯一依据——模型的决策过程会随会话消失,日志不会。

工具粒度也直接影响安全面:一个 delete_ticket(scope="all") 的工具是灾难设计。高危动作要拆细——按 ID 删一个、批量删除走独立的审批流程,粒度细到每一次执行都可以单独审计、单独撤销。给模型暴露粗粒度开关,等于把批量事故的扳机交到它手里。

实战场景

客服 Agent 上线后遇到三类典型问题,恰好对应三个工程要点。第一类:模型偶尔把手机号当运单号传给 get_order,Schema 层校验格式失败后回传 hint"运单号 FY 开头 13 位,手机号查询请改用 search_order_by_customer”,模型下一轮自主改调正确工具,无需人工介入。第二类:查询接口偶发超时,模型陷入"查询-失败-再查询"循环,MAX_ROUNDS 熔断触发后降级转人工,事后从日志看它已经重试了七八次——没有熔断就是实打实的 token 损失。第三类最严重:审计日志发现一次用户未明确确认的退款调用,根因是 refund 工具没有挂人工确认层。补上"高危工具执行前必须用户确认"的拦截后,这类调用全部变成"发起确认-等待用户-执行或取消"三步。三件事的共性:都不是模型问题,都是普通后端工程问题。

检查清单

  • 每个工具定义有清晰的 description 和参数语义,工具数量克制
  • 工具执行前过三道校验:Schema、权限、业务规则
  • 权限校验失败是终态拒绝,不回传给模型重试
  • 工具错误以"错误码 + 说明 + hint"结构回传,不抛异常、不回传堆栈
  • MAX_ROUNDS 熔断配好,超限降级转人工
  • 工具返回值为模型裁剪,不回传全量数据库实体
  • 并行 tool_calls 想清楚执行顺序与部分失败的语义
  • 每次工具调用落审计日志:会话、参数、结果可追溯