FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

一次工具调用超时,就可能让 Agent 整轮失败

每个调用都要返回结果,失败的也不例外;有副作用的工具按顺序执行,再统计循环还会出错多少次。

分享微博

要点速览

  • Claude 可以在一轮中返回多个 tool_use 块。并行还是顺序执行由你决定,取决于工具有没有副作用。
  • 每个调用都需要一个 tool_use_id 对应的 tool_result,失败或被跳过的调用也一样(is_error: true,并附简短原因)。
  • 在贴近真实的测试集上统计工具错误率,同时记录运行时间和调用次数,才能判断一次修复是否真的让 Agent 变好。
示意图:Claude 在一轮中返回三个 tool_use 块。get_order 和 get_stock 并行执行,返回正常的 tool_result 块;get_shipment 超时,但仍返回一个带 is_error: true 的 tool_result,以橙色标出。三个结果合并进一条 role 为 user 的消息。注释:缺少这个结果,整轮就会失败。
Agent 并行调用三个工具时,每个调用都必须在同一条 user 消息里有对应的 tool_result,超时的调用也不例外(标记为 is_error: true)。来源:文中引用的 Anthropic 工具调用文档。

一个客服 Agent 收到问题:“我的订单到哪了?有没有库存可以换货?”它在一轮中返回了三个工具调用。其中两个成功,第三个调用物流系统时超时。如果代码只发回两个结果,整轮就会失败,尽管三分之二的工作已经完成。

这并不罕见。Anthropic 的文档明确说明,Claude 可以在一轮中返回多个 tool_use 块,而 API 不规定它们的执行顺序。可以用 asyncio.gather 或 Promise.all 并发执行,也可以按出现顺序逐个执行。

OpenAI 同样建议默认按多个调用来处理,因为一次响应可能包含零个、一个或多个调用。

对前线部署工程师(FDE)来说,这是日常工作。客户现场的工具都是又慢又不稳定的内部 API:有的只读数据,有的会动真金白银。本文介绍如何构建一个能扛住部分失败的处理循环,以及如何衡量它还会出错多少次。

要构建什么,需要准备什么?

要构建三样东西。第一,一个执行工具调用的函数:只读工具并行执行,有副作用的工具按顺序执行。第二,一个把结果汇总成一条合法消息的函数。第三,一个运行测试集并打印错误率的脚本。

需要准备 Python 和 asyncio、一个已经带着几个工具调用 Claude 的 Agent,并熟悉 tool_use 块的结构。下面的代码是用于演示的精简版,不含 API 调用、认证和重试。贯穿全文的例子是一个订单 Agent,有四个工具:get_order、get_shipment、get_stock(只读)和 issue_refund(有副作用)。

第 1 步:写异步代码之前,先给工具分类

Anthropic 的建议很明确:相互独立的只读操作通常可以安全地并行执行,能降低延迟。有副作用、共享状态或需要严格顺序的工具,最好按顺序执行。所以第一件事是把这套分类写进代码,而不是只记在脑子里。

import asyncio, time

READ_ONLY = {"get_order", "get_shipment", "get_stock"}
SIDE_EFFECT = {"issue_refund"}  # 按模型给出的顺序依次执行

检查: Agent 的每个工具都必须恰好属于两个集合之一。拿不准的工具一律放进 SIDE_EFFECT。跑得慢一点,也比重复退款划算。

第 2 步:单独包装每个调用,避免错误扩散

每个调用单独包装。失败时照样返回 tool_result,带上 is_error: true 和简短说明。Anthropic 的文档正是这样要求的,无论是出错的调用,还是你决定跳过的调用。

async def run_one(block, log):
    start = time.monotonic()
    try:
        out = await TOOLS[block.name](**block.input)
        res = {"type": "tool_result", "tool_use_id": block.id, "content": out}
    except TimeoutError:
        res = {"type": "tool_result", "tool_use_id": block.id, "is_error": True,
               "content": "物流系统 5 秒内未响应。"
                          "可重试 get_shipment 一次,或在不提供送达日期的情况下回答。"}
    except Exception as e:
        res = {"type": "tool_result", "tool_use_id": block.id, "is_error": True,
               "content": f"{block.name} 调用失败:{type(e).__name__}。请检查输入字段。"}
    log.append({"tool": block.name, "is_error": res.get("is_error", False),
                "seconds": time.monotonic() - start})
    return res

注意错误内容。Anthropic 建议错误信息要明确告诉 Agent 该修正什么,而不是转发晦涩的错误码或堆栈跟踪。“重试一次,或在不提供送达日期的情况下回答”给了模型一条出路;只给一个 HTTP 504 字符串,模型只能去猜。

检查: 在 get_shipment 中模拟一次 TimeoutError,确认函数仍返回一个带正确 tool_use_id 的 dict。

第 3 步:只读调用并行执行,其余按顺序执行

async def run_turn(tool_blocks, log):
    reads = [b for b in tool_blocks if b.name in READ_ONLY]
    writes = [b for b in tool_blocks if b.name not in READ_ONLY]
    # 简化处理:所有写调用都等全部读调用完成后再执行。
    results = dict(zip([b.id for b in reads],
                       await asyncio.gather(*(run_one(b, log) for b in reads))))
    failed = None
    for b in writes:
        if failed:
            results[b.id] = {"type": "tool_result", "tool_use_id": b.id, "is_error": True,
                             "content": f"未执行:之前的 {failed} 调用失败。"}
            continue
        r = await run_one(b, log)
        results[b.id] = r
        if r.get("is_error"):
            failed = b.name
    return [results[b.id] for b in tool_blocks]  # 保持原始顺序

写调用的循环参照了 Anthropic 文档中的示例。某个写调用失败后,依赖它的后续调用不再执行,但每个仍会拿到一个错误结果,内容类似“未执行:之前的 write_file 调用失败”。这个精简版把每个后续写调用都视为依赖前一个。

在真实系统中,应更精确地声明依赖关系,让写调用只等待它真正需要的读调用。

检查: 让第一个 issue_refund 失败,确认第二个调用完全没有触及支付系统。

第 4 步:把所有结果放在一条消息里发回

一轮并行调用的所有结果必须一起放进下一条 user 消息。每个结果通过 tool_use_id 与对应的调用匹配,所有 tool_result 块都必须排在任何文本之前。

results = await run_turn(tool_blocks, log)
next_user_message = {"role": "user", "content": results}  # 如有文本,放在最后

如果不需要这种程度的控制,Anthropic 推荐使用 SDK 的 Tool Runner。它会处理包含多个调用的响应,并替你格式化结果。

只有在需要自定义批处理、顺序或错误处理时,才像上面这样自己写循环。如果使用 OpenAI 且想完全避免并行调用,可以用 parallel_tool_calls=false 参数,把每轮限制为零个或一个调用。

第 5 步:用测试集统计错误,而不是凭感觉

处理循环是否有效,只能靠测量。Anthropic 建议基于真实使用场景构建大量评测任务。除了准确率,还要收集每个调用和每个任务的运行时间、工具调用次数、token 数量和工具错误次数。

“查询订单 123”这样的测试用例太简单了。应该从真实工单中取题:客户一次问三件事、订单号输错,或者要求为尚未发货的订单退款。

def summarize(task_logs):
    calls = [c for log in task_logs for c in log]
    if not calls:  # 避免除以零,以及对空列表调用 max()
        return {"tool_error_rate": None, "calls_per_task": 0, "max_call_s": None}
    errors = sum(c["is_error"] for c in calls)
    return {"tool_error_rate": errors / len(calls),
            "calls_per_task": len(calls) / len(task_logs),
            "max_call_s": max(c["seconds"] for c in calls)}

max_call_s 只是最慢的那次调用,不是百分位数。测试集足够大之后,还应计算 p95,避免一次偶发超时扭曲整体情况。

举个假设的例子:20 个测试用例产生 64 次工具调用,其中 8 次带 is_error。工具错误率为 8/64 = 12.5%。查看日志,假设其中 5 次错误来自 get_shipment 超时。

你修改错误信息,让模型只重试一次,再跑同样的 20 个用例,同时比较错误率和每个任务的调用次数。如果错误减少了,调用次数却猛增,说明 Agent 可能在不加区分地重试。

手写循环最容易在哪里出错?

首先要检查的是失败或被跳过却没有产生结果的调用,比如代码捕获异常、记一条日志就继续往下走。Anthropic 的规则很直白:这个调用仍然需要一个带 is_error: true 的 tool_result。其次是把文本放在 tool_result 块前面。

还有一个错误可能造成实际后果:只因为 gather 用着方便,就把有副作用的工具并行执行。另外,不要把原始堆栈跟踪直接塞进 content,然后奇怪 Agent 为什么一再犯同样的错。

这项技能在客户现场如何体现?

客户现场的工具就是客户自己的系统,所以你很可能会被问到:其中某个系统出问题时,Agent 会怎么做。最好提前准备好答案,而不是等别人问起。

有了一张把工具分为只读和有副作用的分类表,你就有材料带去和客户运维团队开工作会。有了在他们自己工单上测出的工具错误率,你汇报的就是一个数字,而不是一场演示。

写简历或面试 FDE 岗位时,就讲这个故事:哪些工具并行执行,错误如何返回给模型,修复前后的错误率各是多少。看岗位描述时,留意与 Agent 可靠性或评测相关的要求,这个故事在那里最有用。

让 Agent 在演示中跑通很容易。能察觉某个工具刚刚失败、只重试一次、仍然给客户答复的 Agent,才是客户愿意放进生产环境的。

这篇文章对你有帮助吗?

3 个信源
路线图上的下一篇 · 阶段 6: 价值度量每步 95% 正确的十步 Agent,四成会失败写代码前就能算出来:即便每步 99%,20 步链路也只剩 82%,减步骤比打磨提示词更管用。