普通接口出了问题通常可以顺着请求一路查下去API、Service、Database哪里报错日志里大多能找到线索。Multi-Agent 则相对麻烦。比如用户看到的结果可能只是“报告少了一段结论”真正的问题却发生在十几分钟前Research Agent 搜索不完整Analysis Agent 调 Tool 超时后重试又读取了旧 ArtifactWriter Agent 最后正常生成了一份错误报告。这种问题只看最终日志很难查清。还要知道一次任务经过了哪些 Agent、调用了哪些 Tool、读取了什么 State 和 Artifact、发生过几次重试。Tracing 和 Observability 的作用就是把这条执行链完整记录下来。一、日志为什么不够假设系统有三个 AgentResearch Agent 负责收集资料Analysis Agent 负责分析Writer Agent 负责生成报告。某次任务结束后用户发现报告引用的是昨天的数据。后台日志看起来却完全正常10:01:02 Research Agent started 10:01:08 Research Agent completed 10:01:08 Analysis Agent started 10:01:14 Analysis Agent completed 10:01:14 Writer Agent started 10:01:21 Writer Agent completed继续查才发现Research Agent 已经生成artifact-102 v2Analysis Agent 当时读取的却是artifact-102 v1。没有 Exception没有 HTTP 500也没有 Agent 明确失败。每一步都执行成功最终结果仍然错了。这类问题在 Agent 系统里很常见单独看每一步都正常连起来以后结果却错了。普通日志更适合回答“某个时间发生了什么”。Multi-Agent 排查的问题比较多这一步属于哪个任务由哪个 Agent 执行是谁触发的调用了哪个 Tool读取了哪份 Artifact发生过几次 Retry这些关系如果没有提前记录事故发生后很难靠日志重新拼出来。二、一次任务一条链工程上通常把一次完整任务记录成一条 Trace。比如用户提交研究最近一周数据库领域的变化并生成一份报告。内部可能经历Task 42 │ ├── Research Agent │ ├── LLM │ ├── Search │ └── Write Artifact │ ├── Analysis Agent │ ├── Read Artifact │ ├── LLM │ └── Write Artifact │ └── Writer Agent ├── Read Artifact └── LLM整条执行链就是 Trace。其中每个具体操作叫 Span。Agent 执行、LLM 调用、Tool 调用、A2A 调用、Artifact 读写都可以分别记录成 Span。每个 Span 会保存自己的开始时间、结束时间、状态和属性再通过父子关系组成完整调用链。监控平台里可能看到Task 42 34.8s ├─ Research Agent 9.3s ├─ Analysis Agent 18.6s │ ├─ LLM 5.2s │ ├─ Tool 5.0s │ └─ Tool Retry 5.1s └─ Writer Agent 6.9s如果现在要查“为什么 Task 42 变慢了”范围很快就能缩小到 Analysis Agent以及发生 Retry 的 Tool。Trace 的作用很直接把一堆离散事件还原成完整执行过程。三、关键标识要贯通真正落地时还有一个常见问题每个 Agent 都有 Trace但彼此没有关联。例如 Agent A 通过 HTTP 调用 Agent BAgent B 再通过 Queue 触发 Agent C。如果三个 Agent 分别创建新的trace_id监控平台最终只能看到三条互不相关的调用记录。所以跨 Agent 调用时要把追踪上下文继续传下去。最基础的三个字段是trace_id标识整条执行链span_id标识当前操作parent_span_id记录当前 Span 的上一级操作。例如整个任务使用trace_idT100。Research Agent 的span_idS10它调用 Search 时创建S11并把parent_span_id设置为S10。这样系统才能恢复出Research Agent S10 ├── Search S11 └── Analysis Agent S12Multi-Agent 还应该额外记录一些业务 IDtask_id业务任务context_id相关上下文agent_id执行 Agenttool_call_id具体 Tool 调用artifact_id读取或生成的 Artifact。比如某个 Span 同时记录task_idtask-42、agent_idanalysis-agent、artifact_idartifact-102-v1。出现问题时就能直接确认 Analysis Agent 当时到底读取了哪一份数据。很多所谓的“Agent 偶尔出错”最终找到的原因其实很具体旧 Artifact、旧 State、Tool 重复调用、Retry 重复执行或者上下文关联错误。四、Span 应该记录什么Span 记录得太少没有排查价值记录得太多又会带来隐私、成本和安全问题。实际工程中可以优先把执行信息记录完整。一个 Agent Span 可以包含{ task_id: task-42, agent: analysis-agent, agent_version: 1.8.2, model: deepseek-flash, prompt_version: analysis-v7, duration_ms: 5240, input_tokens: 8321, output_tokens: 1287, retry_count: 1, input_artifact_id: artifact-102-v1, output_artifact_id: artifact-103-v1, status: success }Tool Span 可以再记录tool、tool_call_id、duration_ms、retry_count、status和error_type。这些结构化数据已经能解决大量问题。任务突然变慢可以查duration_ms某个版本错误增加可以按agent_version或prompt_version对比怀疑读错数据直接检查input_artifact_id。Prompt、Tool 参数和完整返回内容不一定默认保存。更实用的做法是把数据分成两层。第一层记录行为数据调用哪个 Agent、用了什么 Tool、重试多少次、耗时多久、读写了哪些 Artifact。第二层才是内容数据用户输入、Prompt、模型输出、Tool 参数和 Tool 返回结果。很多故障只看行为数据已经足够。比如 Research Agent 一次任务调用 Search 17 次、Retry 4 次总耗时 89 秒。即使完全不看用户内容也能判断这次执行过程有异常。内容数据则可以根据业务情况做脱敏、截断、采样、加密和权限控制。五、指标负责发现异常Trace 适合调查某一条具体任务。比如Task 42 为什么失败如果问题变成最近一周系统是不是越来越慢就需要 Metrics。常用指标可以包括task_success_ratetask_latency_p95agent_error_rateagent_latencytool_error_ratetool_timeout_rateretry_countinput_tokensoutput_tokenscost_per_taskMulti-Agent 还可以增加agents_per_task、handoff_failure_rate、artifact_read_failure、duplicate_execution_count等指标。例如平时create_ticket每五分钟只有两三次 Retry某个时间段突然增加到 37 次这时就可以确认该 Tool 出现异常再进入相关 Trace 找具体任务。整个排查过程通常是Metrics 发现异常 → Trace 找到具体调用 → Logs 查看细节。三者各有用途。Metrics 看趋势Trace 看过程Log 看具体事件。组合起来比直接翻大量日志有效得多。六、实战示例先看一个性能问题。用户反馈部分报告需要两分钟才能生成平时只有二十秒。找到对应的task_idtask-8912打开 TraceTask 8912 121s ├─ Research Agent 18s ├─ Analysis Agent 94s └─ Writer Agent 9s问题已经缩小到 Analysis Agent。继续展开发现其中的database_query连续发生五次 Retry每次都接近十秒。再看 Tool Span{ tool: database_query, error_type: timeout, retry_count: 5 }这时就没有必要继续研究 Prompt。真正要查的是数据库查询、连接池、网络或者 timeout 设置。问题从“为什么 Agent 这么慢”缩小成了“为什么database_query连续 timeout 五次”。范围明确以后排查就简单多了。再看一个更典型的问题重复创建 Ticket。线上偶尔出现两个内容完全相同的 Ticket。如果只有最终日志很容易怀疑 Agent 调用了两次create_ticket。Trace 显示的实际过程却是create_ticket ├─ POST /tickets ├─ Server 创建 Ticket 8271 └─ Client 等待返回时 timeout ↓ Retry ↓ 再次 POST /tickets ↓ Server 创建 Ticket 8272第一次请求已经成功只是结果没有正常返回给调用方。调用方收到 timeout 后触发 Retry于是出现问题。这类问题需要给有问题的操作增加 Idempotency Key也就是幂等键。例如使用task-42:create-ticket:user-193第一次调用时服务端创建 Ticket 8271并保存这个 Key。即使客户端超时第二次请求仍然携带相同 Key。服务端发现这个操作已经执行过直接返回 Ticket 8271不再创建新的记录。没有 Trace 时很容易花大量时间检查 Prompt 和模型。完整调用链出来以后它就是一个典型的“超时 Retry 非幂等操作”问题。Replay 复现偶发故障还有一类问题更难查昨天失败了今天重新运行又正常。这时需要 Replay。为了尽量恢复当时的执行环境Trace 最好保存模型、Prompt 版本、Agent 版本、Workflow 版本、State 版本、Artifact ID 和 Tool 版本。例如系统从 Workflow 2.8.0 升级到 2.8.1 后平均 Retry 次数从 0.3 上升到 3.8排查范围就可以直接缩小到 2.8.1 的改动。Replay 一般有两种方式。一种直接使用历史 Tool Result主要验证后续 Agent 逻辑。另一种重新调用真实 Tool更接近线上环境但外部数据可能已经变化。如果 Tool 会写数据库、发邮件、创建订单、创建 Ticket 或支付Replay 应使用 Mock、Sandbox 或测试环境避免调试时再次产生不必要的问题。总结Multi-Agent 难调试很大一部分原因是执行链变长了。一次任务可能经过多个 Agent、LLM、Tool、State 和 Artifact其中任何一步出现问题最后都可能表现成一句“结果不对”。如果系统只记录最终结果很难找到真正的故障位置。Tracing 把完整调用链记录下来Metrics 用来发现异常趋势Logs 用来查看具体细节Replay 用来恢复事故现场。再配合task_id、trace_id、artifact_id、版本号和幂等设计很多模糊的 Agent 故障都能缩小到某个 Agent、某次 Tool Call、某份 Artifact 或某次 Retry。