多智能体系统为什么需要按任务拆分追踪链路

多智能体系统需要按任务拆分追踪链路，核心原因不是 agent 数量多，而是一次结果由多次委派、上下文交接、工具调用和记忆读写共同决定。把每个 agent 各记一条日志，通常只能看到“谁返回了什么”，看不到“它为什么拿到这份上下文”。

实用的设计是：以一次用户任务作为根 trace，以每个 agent 的执行作为子 span，再把委派、交接、检索、工具和状态变更挂到对应节点。这样遇到错误答案时，可以沿着同一个 task_id 回放，而不是在几套日志里猜测。

一条总链路为什么比多份 agent 日志更容易排错

假设编排器收到“整理一份供应商风险摘要”的请求，先让检索 agent 找资料，再让分析 agent 判断风险，最后由写作 agent 生成摘要。最终答案不准确，可能是检索召回了旧资料，也可能是分析 agent 没收到风险等级规则，还可能是写作 agent 使用了上一次任务残留的记忆。

如果每个组件只输出自己的请求日志，三处日志都可能是 200，甚至每个模型调用都成功。按任务建根 trace 后，链路可以表达为：task → orchestrator → retriever、analyst、writer。OpenTelemetry 将 trace 组织为相互关联的 span，context propagation 负责把关联信息跨进程传递；多智能体系统要做的，是在这些通用机制上补齐 agent 语义。

交接节点要记录哪些信息才不会丢上下文

交接是多智能体链路最容易断开的地方。不要只记录“分析 agent 已启动”，至少保留下面这些稳定字段：

交接内容可以记录摘要、字段名和内容哈希，不必在生产环境无条件保存完整提示词。关键是让接收方能够确认输入边界，例如“供应商列表版本为 7，风险规则版本为 3，检索结果 12 条，已通过字段校验”。

把 agent、工具和记忆读写放在同一棵树上

链路的层级最好反映责任边界，而不是简单按时间排列。一个 agent span 下可以有模型决策、工具调用和记忆操作；工具的子 span 再记录输入类型、结果状态、重试次数和外部资源标识。记忆读取要记录命中的 key 或文档版本，写入要记录写入原因与有效期，避免把敏感正文直接塞进普通日志。

from opentelemetry import trace

tracer = trace.get_tracer("agent-workflow")

def run_research_agent(task_id, query, context_version):
    # 用一个 agent span 包住模型、检索和交接，保证它们属于同一任务。
    with tracer.start_as_current_span("agent.research") as span:
        span.set_attribute("agent.name", "research")
        span.set_attribute("agent.task_id", task_id)
        span.set_attribute("agent.context_version", context_version)

        # 工具调用单独成节点，后续才能区分模型判断与检索失败。
        with tracer.start_as_current_span("tool.search") as tool_span:
            tool_span.set_attribute("tool.name", "supplier_search")
            result = search_supplier_docs(query)
            tool_span.set_attribute("tool.result_count", len(result))

        # 交接前记录契约校验结果，不把完整资料正文写入 span 属性。
        handoff_ok = validate_research_result(result)
        span.add_event("handoff.ready", {"handoff.valid": handoff_ok})
        if not handoff_ok:
            span.set_status(trace.Status(trace.StatusCode.ERROR, "handoff contract failed"))
            raise ValueError("research result does not satisfy handoff contract")
        return result

上面的重点不是照抄某个框架 API，而是保持三层关系：任务标识在每次边界都能取到，工具调用有自己的节点，交接失败能在发送方结束前显式标记。实际接入时还要确认 SDK 的 span 生命周期、导出器和采样策略。

用任务级信号复查链路是否真的可诊断

有了 trace 还不够，建议每次任务至少同时观察五组信号：任务是否完成、每个 agent 的耗时、模型 token 与工具成本、交接和工具失败率、检索或记忆命中质量。仅看 HTTP 状态和模型延迟，会漏掉“调用都成功但答案错了”的认知失败。

上线前可以用下面的清单做一次回放：

• 从用户 task_id 出发，能否找到根 trace 以及所有子 agent？
• 每个 handoff 是否都有发送方、接收方、上下文版本和校验状态？
• 工具输出、记忆读写和检索结果是否能回指触发它们的 agent span？
• 失败重试是否保留原始失败原因，而不是覆盖成最后一次成功？
• 生产采集是否对提示词、工具参数、个人信息和业务机密做了脱敏或采样？

常见问题

多智能体一定要使用 OpenTelemetry 吗？

不一定。关键是跨 agent 传播稳定的关联 ID，并保留父子关系和必要事件；OpenTelemetry 的优势是提供通用的 trace、span 和 context 传播模型，方便接入不同后端。

把所有提示词和工具结果写进 trace 会更容易排错吗？

短期更容易，生产风险也更高。建议开发环境保留较丰富的调试内容，生产环境采用脱敏、字段白名单、摘要或哈希，并给敏感 span 设置更短的保留期。

什么时候应该拆成多条 trace？

同一用户任务内的委派通常保留一条 trace；如果子任务异步运行很久、跨越独立权限域或生命周期已经脱离原请求，可以使用新的 trace，并通过 span link、task_id 和业务事件 ID 保留因果关系。