多智能体系统的"病理学诊断"器:Agent Trace 的算法选型与准确率门控
当把多个LLM Agent串起来协作时，无论是使用LangGraph、CrewAI，还是自研框架，开发者几乎都会撞上同一类问题——这些问题在单Agent系统中根本不会出现。问题集中表现为三种典型形式。
第一种是死锁。Agent A在等B释放资源，B也在等A，系统无声挂起，日志干净得像在睡午觉，没有任何报错。第二种是循环依赖。A把任务交给B，B又转给C，C转了一圈交回A，三个Agent互相踢皮球，token烧光但产出一片空白。第三种是上下文膨胀。对话越拖越长，token累积到模型窗口边缘，上下文被截断，推理质量断崖式下降，前文聊过什么，模型已经完全忘掉。
现有的可观测性工具，比如Langfuse、Phoenix、Helicone，主要回答的是"发生了什么"，它们能给出漂亮的调用链和指标仪表盘。但用户真正想问的是"哪里出了病"，这就需要一个病理学诊断器，而不是观测台。Agent Trace的定位正在于此——用结构化算法直接指证病灶，每个算法在发布前都必须通过100%准确率门控。
下面聊聊四个核心检测器的算法选型思路，以及为什么最终选定这套组合。
死锁检测:为什么是WFG + DFS，而不是简单的超时检测
最容易想到的死锁检测方案，是给每个Agent调用设一个超时，超时未返回就告警。这个方法听起来直接，但实际工程里有两个致命问题：一是慢，死锁的告警要等到超时阈值才会触发，而线上服务往往需要秒级响应；二是漏报，两个Agent之间互相等待的资源，各自占用的时间不到超时阈值，系统卡死但告警器安安静静。
Agent Trace用的是经典的等待图(Wait-For Graph)加增量DFS。每次Agent请求资源时，就在WFG上加一条有向边，边表示"谁在等谁释放"。完成DFS环检测的时间复杂度是O(V+E)，几十个Agent规模下亚毫秒级，根本等不到超时就能发现问题。
具体的代码用法只有4行：
from agent_trace.detectors import DeadlockDetectordeadlock = DeadlockDetector()deadlock.acquire("agent_a", "db_connection")deadlock.acquire("agent_b", "file_lock")deadlock.request("agent_a", "file_lock")deadlock.request("agent_b", "db_connection") # → DeadlockDetected!
在20个场景的基准测试(10个死锁+10个安全路径)上，精确率P和召回率R都达到1.0，也就是说零误报、零漏报。
循环检测:为什么是Tarjan SCC，而不是普通DFS
Agent之间的委派关系天然构成有向图，检环是最经典的需求。很多人第一反应是写一个普通DFS加visited集合，这确实能跑。问题在于，普通DFS找到的"环"其实是回溯边对应的子结构，容易受递归顺序影响，而且对于存在多个环的复杂场景，它会重复报告，定位不准确。
Agent Trace用的是Tarjan强连通分量算法，时间复杂度O(V+E)，一次性输出图中所有的强连通分量，凡是大小大于1的SCC就是真实存在的环，定位精确，不会重复，也不会漏报。
from agent_trace.detectors import CycleDetectordetector = CycleDetector()detector.add_handoff("planner", "researcher")detector.add_handoff("researcher", "writer")detector.add_handoff("writer", "planner") # → CycleDetected!
在50张图的基准测试(25张含环+25张DAG)上，F1分数达到1.0000，零误报零漏报。
上下文膨胀预测:为什么是EMA三层，而不是固定阈值
最容易想到的膨胀检测，是设定一个固定阈值，比如token数量超过100000就告警。这种固定阈值方法，在不同模型、不同任务、不同prompt模板下，误报率极高。GPT-4o跑长文档总结时，100k token是常态，告警会刷屏；Claude跑短指令任务时，30k就告警，但其实还在合理范围。
Agent Trace用的是tiktoken加三层EMA(指数移动平均)：第一层跟踪每步token增量，第二层跟踪整体趋势，第三层做长周期预测。系统不仅能在"已经膨胀"时告警，还能预测未来5步之后的token用量(detector.predict("agent_1", steps_ahead=5))，让上层应用提前触发压缩或摘要。
在100步的对照实验上，MAE(平均绝对误差)为1.0%，告警召回率达到100%。
异常检测:5特征加权投票
除了三类主病灶，Agent Trace还内置了异常检测器。它不像传统机器学习模型那样需要训练集，而是采用5特征加权投票：token历史曲线、span总数、span错误数、handoff深度、循环告警数、上下文token数。这些特征各有权重，任何一个超阈值都会贡献一个分数，总分超过阈值就标为异常。
在100个场景基准测试(50异常+50正常)上，F1=1.0000。
Web UI:火焰图与调用图
光有数字告警还不够，定位问题需要可视化。Agent Trace自带Web UI，默认端口7600，两个核心视图：
火焰图：
横轴是累计token消耗，颜色深度代表本步骤自身token消耗。容器型步骤(比如planner)通常又宽又浅——它们只委派不计算，烧token的叶子步骤(比如writer)既宽又深红，那才是真正的热点。
调用图：
圆形布局，Agent是节点，委派关系是边。Tarjan SCC检出的环用红色箭头标出，页面顶部还会显示告警横幅。
整体面板：
与同类工具的对比
| 维度 | Agent Trace | Langfuse | Phoenix (Arize) | Helicone |
|---|---|---|---|---|
| 死锁检测 | WFG + DFS | 无 | 无 | 无 |
| 循环依赖 | Tarjan SCC | 无 | 无 | 无 |
| 上下文膨胀预测 | EMA 三层 | 无 | 无 | 无 |
| 异常检测 | 5 特征加权投票 | 基础 | 无 | 无 |
| OTel GenAI 语义 | v1.41 全量 | 部分 | 部分 | 无 |
| 零基础设施 | SQLite 默认 | 需 Postgres | 需 ClickHouse | 需 Postgres |
| 准确率门控 | 每模块 100% | N/A | N/A | N/A |
横向来看，Langfuse偏观测平台，Phoenix偏评估，Helicone偏袋里监控，三家各有侧重，但也都偏重。Agent Trace的差异点是病理检测：不抢你的观测仪表盘市场，专门补"哪里出了病"这一段空白。基础设施侧，只用一个SQLite文件，不用Postgres、不用ClickHouse、不用Docker，pip install agent-trace[web]就完事。
仓库与声明
GitHub仓库：github.com/Apageoflove…
148个测试，100%准确率门控，Apache 2.0许可证。
声明：这是个人项目，开发和测试资源有限，功能与结论仅供参考，不构成生产级保证。如有问题欢迎评论指正，Issue和PR也都欢迎。
