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

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

原文: https://fdetimes.net/zh/guides/parallel-tool-calls-partial-failure/

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

```python
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 的文档正是这样要求的，无论是出错的调用，还是你决定跳过的调用。

```python
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 步：只读调用并行执行，其余按顺序执行

```python
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` 块都必须排在任何文本之前。

```python
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”这样的测试用例太简单了。应该从真实工单中取题：客户一次问三件事、订单号输错，或者要求为尚未发货的订单退款。

```python
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，才是客户愿意放进生产环境的。

**本周动手试试:**

- 审查你正在开发的 Agent 中的工具处理循环：找出所有失败调用没有产生 tool_result 的地方，全部修好。
- 从真实工单或日志中写出 20 个测试用例，记录每次工具调用的 is_error 和耗时，第一次算出你的工具错误率。
- 重写最常见的三条工具错误信息，让每条都清楚说明 Agent 下一步该做什么，然后重跑测试集进行对比。

## 信源

- [Parallel tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use)

- [Function calling | OpenAI API](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)
