用统一链路定位多智能体任务故障
通过 OpenTelemetry 将一次任务中的智能体轮次、交接、工具调用和 MCP 服务串入同一条追踪链路,并记录各智能体的执行结果。文章还介绍根因遍历器,用于定位导致任务失败的智能体。
AI 深度解读
多 Agent 系统最难排查的故障,往往是每个 Agent 都显示成功,最后答案却错了。作者给出的办法是:把一次任务中的 Agent、交接、模型调用和工具调用串进同一条 OpenTelemetry trace,再查任务最早在哪次交接中偏离了目标。
这套方案的价值,是把「答案不对」变成能定位、能比较的问题。不过,链路记录能提供证据,自动判定谁出了错仍有前提,尤其不能把语义相似度直接当作责任认定。
每个 Agent 都是绿的,为什么任务还能失败
单独看 Agent 日志,通常只能知道它收到了请求、调用了模型、返回了结果。至于它理解的任务是否与用户要求一致,上游有没有漏传限制条件,这些问题很容易落在两份日志之间。
作者在前一篇设计了交接记录,比较「发送的任务」「接收方理解的任务」和「原始目标」。这一篇补上容器:用一条 trace 保存整个任务的执行过程。trace 可以理解为一次任务的完整档案,span 则是里面的一段具体操作。
一次用户任务对应一条 trace,交接记录才有上下文。
实现从编排器开始:在 run_task 入口创建名为 task 的根 span,记录 app.task.type 和 app.task.goal。示例任务类型是 churn_report,目标文本只保留前 500 个字符。
接下来,每次跨进程调用都必须传递链路上下文。下面这段代码解决 HTTP 调用中的传播问题:
import httpx
def call_agent(name: str, payload: dict) -> dict:
headers = {}
inject(headers) # 添加 traceparent / tracestate
r = httpx.post(AGENT_URLS[name], json=payload, headers=headers, timeout=120)
return r.json()
关键在 inject(headers):它把当前上下文写入请求头,通过 W3C traceparent 等字段连接两端。timeout=120 只是示例调用参数,不能代替链路传播。接收方还要执行 extract(dict(request.headers)),并将结果作为 start_as_current_span(..., context=ctx) 的上下文。
走队列也一样,只是载体变成消息体:生产者用 inject(carrier),发送 {"task": step, "otel": carrier};消费者通过 extract(msg["otel"]) 恢复上下文。
MCP server 和下游服务也要接上。任何一跳漏传,都可能重新裂成几条互不相干的 trace。
交接要单独记录,版本和结果也要分开标
链路接通之后,还要解决「打开以后看得懂」的问题。
作者建议每轮 Agent 执行各占一个 span,统一命名为 invoke_agent X,再记录名称、角色、模型和版本。示例中,researcher、writer、reviewer 分别使用 researcher-v7、writer-v12、reviewer-v4;模型字段是占位值 your-model-id,没有指定实际模型。
这些版本标签很实用。writer 的提示词和 reviewer 的规则可能分开上线,只记录整套系统版本,质量下降时仍然难以缩小范围。
交接则使用独立的 handoff A->B span,记录发送方、接收方、任务、上下文字段名、token 数、权限和原始目标。接收方返回一句自己理解的任务,再写入 app.handoff.task_understood。
示例把交接任务和理解结果截到 1000 个字符,原始目标截到 500 个字符。这样,后端能直接比较任务传递前后的变化,但截断内容也可能丢失关键限定条件。
层级上,作者采用 task → agent → handoff → agent → model call → tool call 的组织方式,统一使用 invoke_agent X、handoff A->B、execute_tool Y 等名称。它表达的是组织原则;文中的实际树里,chat search_strategy、execute_tool sql_query、execute_tool web_fetch 是 researcher 下的同级操作,不能机械地认为每次工具调用都必须嵌在模型调用下面。
最后,每个 Agent 都记录自己的结果:
ok表示正常完成。degraded表示结果质量下降。failed表示执行失败。rejected_input表示拒绝处理输入。
结果写入 app.agent.outcome,原因写入 app.agent.outcome_reason;failed 和 rejected_input 同时设置 StatusCode.ERROR。判断依据可以来自 schema 校验、交接偏移评分、工具错误、reviewer 判定或抽样评估。
这里要区分执行状态与业务质量。模型正常返回文本,只能证明调用完成,不能证明任务完成。
自动找第一处异常,能定位到什么程度
作者提供了一个小函数,遍历同一条 trace 导出的 spans,依次检查交接语义偏移、Agent 异常结果和工具错误:
from dataclasses import dataclass
@dataclass
class Suspect:
span_name: str
agent: str
reason: str
def first_bad_hop(spans: list[dict], drift, threshold=0.75) -> Suspect | None:
"""spans:同一条 trace,按开始时间排序。"""
for s in spans:
a = s["attributes"]
# 1. 交接后接收方理解的任务偏离了目标
if s["name"].startswith("handoff "):
score = drift(a.get("app.handoff.task_understood", ""),
a.get("app.task.original_goal", ""))
if score < threshold:
return Suspect(s["name"], a["app.handoff.receiver"],
f"task changed shape (similarity {score:.2f})")
# 2. Agent 将自己的输出标记为失败或降级
if a.get("app.agent.outcome") in ("failed", "degraded"):
return Suspect(s["name"], a.get("gen_ai.agent.name", "?"),
a.get("app.agent.outcome_reason", "agent reported failure"))
# 3. 任务完成前发生了工具错误
if a.get("gen_ai.operation.name") == "execute_tool" and s["status"] == "ERROR":
return Suspect(s["name"], a.get("gen_ai.tool.name", "?"),
"tool error before task completed")
return None
要留意 if score < threshold:默认阈值是 0.75,但原文没有给出 drift 的实现、校准方法或准确率。它是一段定位逻辑示例,还不是可以直接信任的故障裁判。
作者沿用前文的 EU-churn 案例,得到 handoff planner->researcher 的相似度 0.71,因此返回 researcher 为嫌疑对象。原文展示的是这个案例结果,没有提供批量实验或对照数据。
把失败任务都跑一遍,再按 span_name 聚合,可以形成交接问题的排序清单。这比笼统地说「Agent 不稳定」更方便安排修复。
生产使用还需要四项约束:采样按整项任务保留或丢弃;大属性截断,完整载荷放入以 span ID 关联的日志;客户数据在离开进程前脱敏;属性名集中管理,因为作者指出 OpenTelemetry 的 GenAI conventions 仍处于 Development 状态。作者还建议通过 OpenTelemetry Collector 的尾部采样保留 100% 的失败或高风险任务,但具体识别和采样配置没有展开。
我的判断
我认同先把传播、交接和结果记录完整,再讨论自动归因。与分别查看各服务日志相比,这种方式把查询入口统一到了任务上;与只看最终答案的评估相比,它能提供中间过程证据。两者仍需配合。
第一处可见异常适合当调查入口,不能直接等同于根因。
例如,planner 合理地把总目标拆成子任务,researcher 的任务复述与原始目标相似度偏低,并不必然代表理解错误。函数把接收方写入 Suspect.agent,也无法证明责任在接收方:发送方可能已经漏掉必要条件。
代码还有几处边界。它按开始时间排序,父交接 span 可能先于内部 Agent 被检查,但其 task_understood 是执行后才返回的;并发执行时,这个顺序尤其不能直接当作因果顺序。它会把任何工具 ERROR 当作嫌疑,却没有判断后续是否成功重试;rejected_input 虽被标记为错误,也不在 Agent 结果检查的分支里。
所以,原文最扎实的是记录方案。自动归因部分更接近经验规则,缺少对照数据,适合辅助排查,不宜直接用于追责或自动回滚。
能拿来做什么
- 如果你的 Node 服务负责调用多个 Agent,可以先检查 HTTP、队列和 MCP 三条路径是否都传播了上下文,再用一次完整任务确认它们能出现在同一条 trace 中。
- 给每轮 Agent 执行补上角色、模型、提示词或配置版本,以及输出校验结果,让「调用成功」和「产出合格」能分别查询。
- 从最容易出错的一条交接开始,记录发送任务、必要限制和接收方复述,人工核对若干失败案例后,再决定是否引入语义偏移评分及阈值。
- 将
first_bad_hop的输出用于生成待调查清单,同时保留重试结果、子任务关系和最终评估,避免把已经恢复的工具错误当成任务根因。