多 Agent 出错时别只盯 Trace：用 AgentPulse 把异常、路由变化与上游调查路径拆开看
多 Agent 系统出现结果变差时，团队通常已经不缺 trace：每次模型调用的 token、延迟、工具调用和错误都能查到。真正困难的是把这些记录变成一个排查起点。最终负责验收的 Agent 成功率下降，未必说明它自身发生了变化；原因可能是上游 Agent 的提示词改动、模型替换、上下文缩短，或者路由把流量导向了另一条链路。
AgentPulse 是一个 MIT 许可的 Python 开源参考实现，关注的正是这一步“调查”，而不是另造一个通用追踪平台。它把采集到的调用、交接和 DAG 数据写进本地 SQLite，再用同一套漂移分析引擎驱动 Flask 仪表盘、终端 CLI 与 MCP Server。项目明确将自己定位为 reference implementation；需要大规模托管 tracing 的团队，仍应选择成熟的可观测性产品。这个边界很重要：它适合用来学习调查模型、验证内部方案，或在小规模系统中做原型，而不是直接替代生产级观测平台。
Trace 回答“发生了什么”，调查要回答“从哪里开始查”
把所有异常压成一个 anomaly score，看似简洁，实际上会混淆不同故障类型。AgentPulse 将它们至少拆为三层：
- Agent 漂移：某个 Agent 的输出、输入上下文、延迟或重调用频率发生变化；
- 交接漂移：上游传给下游的 payload 变短或膨胀，交接后出现重试、耗时或成功率变化；
- 路由漂移：原有路径消失、新路径出现，或某条路径的流量占比显著改变。
这种划分的价值在于避免“谁报错就修谁”。假设 writer 的 prompt 或模型在某次发布后变化，writer 产出的内容开始膨胀；下游 critic 收到的输入虽然合法，但处理时间增加、最终成功率下降。症状出现在 critic，调查路径却应沿 handoff graph 回溯到 writer。AgentPulse 的设计是从结果违例向上游走，寻找“输入稳定、但自身输出或行为改变”的组件，并把完整路径展示出来。
这里必须保留工程上的谨慎：它输出的是调查路径，不是被证明的因果关系。共同发生的配置、prompt 或模型变更可以提高怀疑优先级，却不能替代复现实验、diff 审查和回滚验证。
本地链路：采集、SQLite 与三种查看界面
AgentPulse 的数据流很直接：应用在进程内调用 instrument()；SDK 对 OpenAI、Anthropic SDK 做 patch，并在可用时接入 AutoGen 与 LangChain 的事件/回调；事件经 storage 写入每个项目一份的 db/ SQLite 文件；analysis 层再计算指标、异常、漂移与调查链。它不要求单独部署服务端或守护进程。
同一引擎有三种入口。Flask Dashboard 用于浏览运行记录、时间线、DAG、趋势和 Drift Investigation；cli.py 把结果打印成终端卡片，适合每日巡检；agentpulse_mcp.py 则把相同发现提供给 Claude Code 或 Claude Desktop。三者共用引擎的好处是：人看仪表盘、值班工程师跑 CLI、编码 Agent 发起调查时，至少不会因为三套规则而得到互相矛盾的“漂移”定义。
项目把数据保留在本机，采集和浏览 dashboard 不需要 API key。只有可选的“下一步检查建议”功能会使用 ANTHROPIC_API_KEY；没有该 key 时，MCP 仍可返回确定性的检查步骤。这种分层对内部开发环境很实用：先保证原始运行数据不离开当前机器，再决定是否把摘要交给外部模型。
先跑演示数据，再接自己的系统
仓库附带一个 db/demo.db 演示项目。官方 README 将其描述为一个四 Agent 内容流水线，包含 120 次运行、四个 prompt version 与一段漂移样本。先跑它比直接接生产任务更合适，因为你可以先确认团队是否认同“agent / handoff / route 分开看”的调查方式。
git clone https://github.com/prove-ai/agentpulse.git cd agentpulse python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt python reporter/dashboard.py
然后访问 http://localhost:5001。如果要接自己的系统，应在入口文件、且在导入 Agent 相关模块之前初始化：
import sys; sys.path.insert(0, '/path/to/agentpulse') from sdk import instrument instrument(task_type='my-system', prompt_version=1, db_name='my-system')
这会把数据写入 db/my-system.db。不过“两行接入”并非适用于所有编排方式：SelectorGroupChat 形式的 AutoGen，以及 LangChain、LangGraph 与依赖 LangChain callbacks 的框架，能够暴露较完整的边界信息；自行用原生 OpenAI/Anthropic SDK 和 asyncio.gather 编排时，SDK patch 只能自动记录 token、延迟和模型，仍需手动管理 run 生命周期、Agent 边界和 turn。不要把自动采集到的调用指标误当成完整的多 Agent 因果图。
用 CLI 把排查变成固定例行流程
仪表盘适合回看，CLI 更适合把问题带进日常值班或发布流程。下面的命令均来自项目的 cli.py：
python cli.py python cli.py --project demo --range 7d --min-severity drift python cli.py --next demo:chain0 python cli.py --compare --project demo python cli.py --compare --project demo --all
值得借鉴的是严重性判定的取舍。项目并不因为一个指标移动就直接升级为严重问题：结果层面的阈值违例还需要同期的强支持信号，以及可能造成变化的事件相互印证；单独移动的指标会留在低置信候选中。对真实系统而言，这比“阈值一过就报警”更接近可操作的告警策略——先把注意力集中在有结果影响、存在上游变化线索的链路，再回看弱信号。
让 MCP 帮忙调查，但别把结论交给它
AgentPulse 提供三个 MCP 工具：get_todays_finding 获取当前活动发现，get_version_comparison 比较版本，get_next_check_steps 返回后续检查建议。仓库内已有项目级 .mcp.json，在已创建 .venv 的前提下可在仓库目录直接启动 Claude Code：
cd agentpulse claude
也可以把 server 显式注册到其他目录：
claude mcp add agentpulse -- /path/to/agentpulse/.venv/bin/python /path/to/agentpulse/agentpulse_mcp.py
合适的用法是让 Agent 汇总“哪个组件先变、相关版本变更在哪里、接下来该查哪些日志或配置”，再由工程师验证。尤其是 prompt、模型和工具版本都可能同时变动时，MCP 的建议应当是排查 checklist，而非自动修复指令。应把原始 trace、配置 diff、回归测试和可回滚发布作为最终证据。
规则不是魔法：把阈值和基线纳入代码审查
项目把 handoff 规则放在 config/drift_rules.yaml。例如，payload 缩短超过一定幅度、同时下游重调用、失败率或成功率出现不利变化，才更像“弱上下文”而不是一次随机波动；payload 变大并伴随下游耗时或重调用增加，则更接近“上下文膨胀”。路由频率增加、而后续成本、时延或失败率走坏时，才值得优先检查路由器是否过度使用某条路径。
这些阈值不能原样搬进每个团队。不同模型、任务长度、缓存策略与并行度都会改变正常波动范围。更稳妥的落地顺序是：保留一段已验证的基线运行；把 prompt、模型、工具和路由变更写成可关联的事件；先以候选信号观察一两个发布周期；再依据误报和漏报调整窗口、最小样本数与严重性规则。项目还用指标快照测试固定演示数据的图表数值，这也提示了一个实践原则：分析引擎本身的重构要有回归保护，否则监控规则变了，团队可能把规则变化误读成系统漂移。
采用前的三个边界
第一，样本量不足时不要过度解释趋势。项目规则本身也要求前后窗口有足够出现次数；低频 Agent 或新路由更适合先标为观察项。第二，指标的方向性要由业务定义：输出变长有时是冗余，也可能是任务变复杂；成功率下降是否严重，还要看任务集合是否变化。第三，本地 SQLite 很适合原型和单机调查，但跨团队留存、权限、聚合和高并发写入仍需要另行设计。第四，任何把“上游起点”连到某次发布的结论，都应保留可复现输入、版本号和时间范围，方便后来者重新审阅。
AgentPulse 最有价值的地方，不是承诺“自动找出根因”，而是把多 Agent 观测从一张调用清单推进为可检验的调查顺序：先区分行为、交接与路由；再把下游症状回溯到可能的上游起点；最后用版本对比、代码审查和复现来推翻或确认假设。对于正在搭建内部 Agent 平台的团队，这比多加一个漂亮仪表盘更值得先讨论。