Agent 可观测 + 全链路追踪

这个 pack 包含什么

某天你的 agent 静默地在两个工具之间循环了 47 轮，最后给出一个自信但错的答案 — 那一刻你会希望自己当初装了 span 级别的追踪，而不是只有按 prompt 看 token 账单的图。这个 pack 是给 ML / LLM 工程师准备的，他们要重建 agent 到底做了什么：哪个子 agent 触发了、每次 tool 调用进去的参数是啥、retry 吃了几次、planner 在转向之前在想什么。

跟 LLM Observability pack 有啥区别

如果你不确定装哪个：LLM Observability 是运行时遥测层 — token 成本、p95 延迟、错误率、prompt 版本对比 dashboard。受众是任何把 LLM 调用上线的人。Agent Observability + Tracing 是 agent 系统的调试层 — 一个用户请求会扇出 10–100 次 LLM 调用、工具调用、子 agent 切换。受众是那个盯着一段 4 分钟 agent 运行结果是垃圾的工程师，想搞清楚是哪一步在撒谎。

成本 dashboard 告诉你这个月账单涨了 30%。深度 trace 告诉你planner 子 agent 重复了同一个搜索 8 次，因为 tool 返回空数组而 prompt 没处理这种情况。两个都要，但它们回答的是不同问题。

按这个顺序装

# 整套
tokrepo install pack/agent-observability-tracing

# 或一层一层装
tokrepo install langfuse        # 1. trace 存储 + UI
tokrepo install opentelemetry-llm  # 2. 一次插桩、后续随便换后端
tokrepo install phoenix         # 3. eval 串联到每条 trace

五层，按这个顺序装：

1. 插桩器 — 包装你的 LLM SDK 和 agent 框架。默认选 OpenTelemetry + OpenInference 语义约定：一次插桩，换后端不用改代码。如果你是 LangChain 重度用户，自带的 langchain_core.tracers 直接写到 LangSmith / Langfuse。
2. Trace store + UI — Langfuse 自部署（数据自主）、LangSmith Cloud（零运维 + LangChain 紧耦合）、Phoenix 本地（notebook 友好 + 零基建）、Helicone 代理（完全不装 SDK）。四个现在都吃 OTel span。
3. Eval 串联 — 把离线 eval（LLM-as-judge / 检索召回率 / tool 调用正确率）接到同一个 trace store，每个 span 都带质量分。Phoenix 和 Langfuse 都内置；LangSmith 叫 'feedback'。
4. 告警 — 在 trace 级别异常上触发，不只是单次调用：agent 跑了 >20 步、retry 深度 >5、子 agent 没调用预期 tool、planner 输出缺必填 schema。这些都是 per-prompt dashboard 根本看不见的失败模式。
5. 会话回放 — AgentOps 和 Helicone 都把 span 归为 'session'（一个用户请求 = 一个 session）。多 agent 系统这个是必装项，没有它你在时间线里根本分不开两个并发跑的用户请求。

常见踩坑

• 只追 LLM 调用，没追 tool 调用 — 模型给出 tool 调用、你的代码执行 tool、结果喂回下一轮。只插桩 LLM SDK，tool 执行就是黑洞。把 tool 分发器也用同一个 tracer 包起来。
• 子 agent 切换没传 parent_span_id — 如果子 agent B 是 A 启动的，B 的 span 必须带 A 的 trace ID。否则 UI 显示两条没关联的时间线，你根本看不出谁调用了谁。
• 完整推理链写成一个大字段 — 一个 30 步反思循环不该是一个巨型字符串字段 — 应该是 reflection 父 span 下 30 个兄弟 span。过滤、搜索、diff 在 blob 形态下全废。
• Agent trace 均匀采样 — 普通 run 采样 10%，但出错的 / 触发 max retries 的 / eval 分低于阈值的 100% 留下。需要调试的 bug 恰好就是你会丢掉的那些 run。
• 被厂商锁住 span 格式 — 用 OpenInference / OpenTelemetry GenAI 语义约定。这个 pack 里每个后端都吃这个。手写私有 JSON 就意味着迁移后端时整个插桩要重写。
• 没把 prompt 版本和 trace 关联起来 — 这条 trace 是 prompt v7 跑的，但你现在已经在用 v9，trace UI 必须能看到版本号，才能 diff 新旧行为。Langfuse 和 LangSmith 都支持，第一天就接上。

跟这些 pack 搭配使用

Agent Observability 是调试器。LLM Observability pack 是生产 dashboard。Multi-Agent Frameworks pack 是被追踪的系统（LangGraph / CrewAI / AutoGen）。LLM Eval & Guardrails pack 是把原始 trace 转换成质量信号、并落到同一个 dashboard 的评分引擎。真做生产的团队四个都装 — 没有 eval 的 observability 就是漂亮时间线、没有 trace 的 eval 就是平均数。