基础篇
进阶篇
高频篇
精选篇
手写篇
面经篇
AI 篇
原理篇
每日一题
小程序题库
  • 知识卡片碎片时间过考点
  • 场景篇按分类整理的大前端场景考点
  • 历年面经按年份追踪真实考点
  • 算法题库NEW在线编码即时判题
  • 专项自测100 题快速查漏
  • 前端基础
    • HTTP从报文一路讲到 HTTPS
    • 浏览器渲染、事件循环、进程
    • 计算机基础Linux、网络、操作系统
  • 进阶专项
    • 设计模式23 种模式怎么用
    • 前端系统进阶学习大型项目工程化
    • 前端综合文章长期沉淀的实践文
  • 工程与工具
    • Node学习指南从环境搭建到服务端
    • NPM工作流script、依赖与发布
    • Docker容器化部署上手
    • Canvas图形与动画实战
  • 路线与导图
    • 思维导图知识点全景图
    • 学习路线按图索骥不跑偏
  • 动态
    • 公众号动态公众号历史文章
    • 博客动态站长的技术博客
    • 开发者导航常用工具与文档站
    • AI 热点每日 AI 资讯与动向
AI 工作台
旧版
AIHT
内容
精选全部 AI 动态热点榜AI 日报收藏
分类
模型行业编程产品技术观点开源
更多
Agent 接入
返回首页开发者导航
AIHT
精选 / 资讯详情
8.0
热点
AI SCORE
技术实践2026-11-18 13:54

多智能体故障排查:从上下文到工具调用

dev.to · AI#多智能体#调试#可观测性
Editor brief · 编辑速览

文章将多智能体异常归因于协作契约、状态共享和可观测性等系统问题,列出上下文漂移、无限委派、决策冲突、工具静默失败及幻觉传播等故障。内容介绍配套调试示例,并强调追踪与可观测性。

文章思维导图
Knowledge map
拖拽缩放
AI deep read

AI 深度解读

多 Agent 系统出错,未必是模型能力不够。作者把常见故障归成六类:约束传丢、循环委派、决策冲突、工具错误被掩盖、幻觉逐级扩散,以及成本和延迟失控。多个 Agent 之间缺少明确的协作规则,系统也缺少足够的运行记录。

这篇的价值在于把「回答不对」拆成可以定位的工程问题。示例使用普通 Python,思路可迁移到 LangGraph、CrewAI、AutoGen 或自建编排器。不过,原文提供的是防护模式和示意代码,没有给出生产对照实验,不能把建议直接当成效果保证。

约束为什么传几次就变了

单次 LLM 调用的输入、输出比较容易核对,多 Agent 链路却会不断改写上下文。前一个 Agent 换一种表述,后一个就可能做出不同决定;问题在 Agent D 暴露,源头却可能是 Agent B 发错了消息。

作者举的例子是,用户要求「只允许在 14 天内退款」,经过三次交接,变成了模糊的「适用退款政策」。信息没有完全消失,但决定结果的边界丢了。

作者建议把任务交接改成带类型的数据结构,将不可改写的约束与可编辑的工作笔记分开。示例依赖 pydantic,安装命令是 pip install pydantic:

from pydantic import BaseModel

class TaskEnvelope(BaseModel):
    task_id: str
    user_goal: str
    hard_constraints: list[str]   # Agent 不得改写
    working_notes: str = ""       # Agent 可以编辑

def handoff(envelope: TaskEnvelope, new_notes: str) -> TaskEnvelope:
    # 逐字保留约束,只更新笔记
    return envelope.model_copy(update={"working_notes": new_notes})

关键是 model_copy(update={"working_notes": new_notes}):这条交接路径只更新笔记。但 hard_constraints 仍是普通列表,类型声明并没有让它自动变成不可修改的数据,约束保护还要靠编排层落实。

作者还建议在流程结束时,通过规则检查或低成本 verifier Agent,核对最终输出是否符合约束。

重要约束应当作为数据传递,并在出口重新核验。

幻觉传播也是类似的问题。Agent A 编出一个细节,B 将其视为事实,C 再据此给建议,错误便获得了越来越完整的包装。原文用 Claim(BaseModel) 为每条断言增加 text 和 source: str | None,来源可以是工具名或文档 ID;filter_unverified() 丢弃没有来源的断言,并用 emit_metric("unsourced_claims_dropped", dropped) 记录数量。

但这段代码只检查来源字段是否存在,没有检查来源是否真实、是否支持断言。「带来源」只是后续核验的入口。

Agent 互相推活,谁负责让它停下来

第二类故障是循环委派:planner 把任务交给 researcher,researcher 因为不确定又请 planner 澄清,两者反复交接。每一步看起来都有理由,整个请求却没有进展。

作者用跳数预算和重复状态检测限制这种循环:

from collections import Counter

class LoopGuard:
    def __init__(self, max_hops: int = 12, max_repeats: int = 3):
        self.max_hops = max_hops
        self.max_repeats = max_repeats
        self.hops = 0
        self.seen = Counter()

    def check(self, sender: str, receiver: str, payload_hash: str):
        self.hops += 1
        key = (sender, receiver, payload_hash)
        self.seen[key] += 1

        if self.hops > self.max_hops:
            raise RuntimeError(f"Hop budget exceeded ({self.max_hops})")
        if self.seen[key] >= self.max_repeats:
            raise RuntimeError(f"Loop detected: {sender} -> {receiver}")

要盯住两个比较条件:默认允许 12 次交接,第 13 次触发超限;同一个发送方、接收方和 payload_hash 组合,第 3 次出现就报循环。每条消息都要调用 check(),漏接的路径仍可能失控。

这里也有未解决的细节:原文没有说明如何生成 payload_hash。如果每轮只是措辞稍变,直接对文本求哈希可能识别不出语义上的重复,此时总跳数上限仍能兜底。

第三类故障是决策冲突。一个 Agent 批准操作,另一个阻止操作,如果系统采用最后返回的答案,实际决定权就交给了响应速度。

作者用 AUTHORITY 显式划分权限:refund_amount 归 billing_agent,tone 归 support_agent。resolve() 遇到没有负责人的字段就抛出 ValueError;提案不一致时调用 log_conflict(),最后采用字段负责人的意见。冲突率上升,可以作为检查角色划分和提示词的信号。

循环要有停止条件,分歧要有裁决规则。这两件事都应该由编排层执行。

工具失败和费用上涨,要从调用记录里找原因

第四类故障很容易被流畅的回答掩盖:工具返回了错误、空列表或超时,Agent 却继续报告一个看似合理的结果。

原文的 safe_tool() 将结果统一包装成 status 和 data:正常结果是 ok,None、[]、{} 被归为 empty,异常被归为 error,并保存错误信息。无论结果如何,都通过 record_span() 记录工具耗时。

作者同时要求 Agent:只要 status 不是 ok,就报告失败,不得自行推断结果。不过,包装函数并没有主动设置超时,也没有强制阻断后续生成。空列表是否属于失败,也需要结合工具语义判断,例如搜索没有命中可能就是有效结果。

第六类故障是成本和延迟膨胀。原文用演示时 4 秒、花费几分钱,生产时 40 秒、每次花费数美元来描述症状,但没有交代测量条件,应把它看作示意场景。

作者建议按 Agent 分别统计 token 和耗时。RunStats.add() 累加各 Agent 的数据,hottest() 找出 token 消耗最多的 Agent,再考虑缩短上下文、缓存结果,或者与相邻 Agent 合并。

这里的 token 数也不完全等于费用;如果各 Agent 使用不同价格的模型,还需要补充模型和计费信息。

作者最后将这些防护汇总到结构化追踪(trace)。示例运行 ID 为 r_8f21,其中一条 span 记录了 planner 到 researcher 的交接:tokens 为 812,latency_ms 为 1430,tool_status 为 ok,termination 为 null。使用 OpenTelemetry 时,每次 Agent 调用可以映射为一个 span,复用现有看板。

这些字段能展示调用路径和开销,但若要解释为何遗漏约束、为何发生分歧,还需关联任务约束、提案和核验结果。原文的结构只是起点。

我的判断

我赞同作者把排查重点放在系统边界上。类型校验、调用预算、权限归属、错误协议和追踪,都能让故障更容易被发现和定位。对于前端、Node 开发者,这些也都是熟悉的工程手段。

但「多数 Agent 故障是系统问题」在原文中没有统计支持;「一个提示得当的 Agent 可能胜过三个一般的 Agent」也没有对照数据。这些是有启发性的经验判断。

结构化字段能降低歧义,不能自动保证内容正确。

Pydantic 检查结构,无法证明业务约束完整;来源字段非空,无法证明断言有据;工具返回 error,也无法保证模型一定停止编造。因此,涉及明确业务边界的检查,应尽量由程序执行,语义判断再交给核验模型,并接受核验本身也可能出错。

和单 Agent 加工具相比,多 Agent 增加了交接、协调和重复上下文的开销。是否值得拆分,应在同一组任务上比较质量、延迟和费用。原文没有提供这样的比较,不能据此认定多 Agent 或单 Agent 普遍更优。

能拿来做什么

  • 给现有 Node Agent 编排器定义统一的交接结构,保留任务 ID、原始目标和硬约束;针对 AI 编程任务,把允许修改的目录等已有要求放入独立字段,并在交付前核对。
  • 在消息分发入口集中执行跳数和重复状态检查,先将原文的 max_hops=12、max_repeats=3 作为待验证的起始配置,再依据真实任务调整,同时明确超限后向用户返回什么。
  • 为工具调用统一返回成功、空结果和错误状态,并按工具语义决定后续处理;对于失败后无法继续的步骤,由编排层阻止继续执行。
  • 在拆出更多 Agent 前,先记录每个 Agent 的 token、耗时、重试和终止原因,再用同一批任务比较单 Agent 与多 Agent 方案,确认新增角色带来的收益能覆盖开销。
Original source

本文由 AI 通读原文后重新编写,观点部分为站内判断,细节以原文为准,来源 dev.to · AI,原文版权归原作者所有。

阅读原文
上一篇
编程智能体拒答后,也要交代已做的修改
下一篇
子智能体的小任务,为何消耗大量上下文

资讯速览

dev.to · AI · 2026-11-18 13:54

AI 评分 8.0 / 10

相关标签

#多智能体#调试#可观测性

继续阅读

  • 跨层复用 KV 缓存,探索推理显存压缩
  • 编程智能体拒答后,也要交代已做的修改
  • 子智能体的小任务,为何消耗大量上下文
  • 把 AI 调研结果变成团队可复用资产
  • GPT-6.2 双模型上线,Sol 编程跑分接近旗舰