一次工具调用超时,就可能让 Agent 整轮失败
每个调用都要返回结果,失败的也不例外;有副作用的工具按顺序执行,再统计循环还会出错多少次。
要点速览
- Claude 可以在一轮中返回多个 tool_use 块。并行还是顺序执行由你决定,取决于工具有没有副作用。
- 每个调用都需要一个 tool_use_id 对应的 tool_result,失败或被跳过的调用也一样(is_error: true,并附简短原因)。
- 在贴近真实的测试集上统计工具错误率,同时记录运行时间和调用次数,才能判断一次修复是否真的让 Agent 变好。
一个客服 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,才是客户愿意放进生产环境的。
这篇文章对你有帮助吗?
感谢你的反馈!