多智能体系统可观测性实践：链路追踪、会话隔离与故障隔离

背景

多智能体系统由多个具备不同职责的 Agent 协同完成任务，具有链路长、异步消息多、状态分散等特点。一旦某个环节出现异常，排查往往需要在多个 Agent 之间来回追踪，定位成本很高。本文结合一个多智能体项目的实践，分享可观测性建设的几条经验。

核心原则

1. 旁路化：观测逻辑不能侵入主链路。所有观测调用都应可被降级，即使观测组件本身异常，也不能影响业务 Agent 的正常执行。

2. 全链路追踪：为每次用户请求生成全局 trace_id，并在 Agent 调用、命令执行、后端请求之间透传，形成完整的调用链。

3. 会话隔离：多会话并发时，观测上下文必须按 session 隔离，避免相互覆盖。

4. 采样与配额：观测数据应有采样率和容量上限，防止观测包成为主链路的故障源。

具体实现

以一个校园报修多智能体系统为例，观测模块被拆分为独立的旁路包，包含以下部分：

• schema：定义观测数据的结构，包括 trace、span、事件类型等。
• trace：负责 trace_id 的生成、保存、加载与清理，支持按 session_id 隔离上下文文件。
• sink：定义观测数据的输出方式，支持本地 JSON 文件与远程上报。
• collector：聚合观测数据并写入 sink。
• wrapper：包装命令执行与 Agent 调用，自动埋点。

在 Web 服务入口生成 trace_id，并通过上下文透传到每个 Agent 的命令执行过程中；每个 Agent 执行的命令都会记录命令与 Agent 的映射关系，便于回溯。

踩坑记录

并发覆盖：早期实现把 trace 上下文写入全局共享文件，多会话并发时互相覆盖，导致追踪链路错乱。后来改为按 session_id 隔离文件，并优先从环境变量读取 trace_id，问题得以解决。

观测包异常影响主链路：观测逻辑一旦抛出异常，会中断 Agent 的命令执行。修复方式是对所有观测调用做异常捕获，失败时仅记录本地日志，不向上抛出。

效果与总结

改造后，全链路可追踪，问题定位从"猜"变成"看"；同时通过 40 余个测试覆盖核心验收标准，保证观测模块自身不回归。可观测性是多智能体系统稳定性的基础设施，建议遵循旁路化、会话隔离、故障隔离三条原则，让观测成为系统的"安全网"而非"故障源"。