可观测性

Agent 失败常是 「哪一步 tool 选错 / 上下文被截断」——没有 trace 只能猜。本课讲 LangSmith、Langfuse、Helicone、结构化追踪 在 ai-agents 路线图 中的用法；与 aga-eval 互补：观测发现个案，评测衡量趋势。

学习目标

• 为每次 run 记录 span：LLM、tool、检索、总延迟
• 对比托管 tracing 与自建 OpenTelemetry
• 平衡调试信息与隐私（勿 log 全 prompt PII）

该记什么

with trace.run("support_agent", user_id=hash(uid)) as run:
    with run.span("llm_plan", model="gpt-4o-mini") as s:
        resp = llm.chat(...)
        s.set(tokens_in=..., tokens_out=..., latency_ms=...)
    with run.span("tool", name="search_docs") as s:
        result = search_docs(query)
        s.set(top_k=5, score_max=result[0].score)
    run.set_output(final_answer, citation_count=len(cites))

字段	用途
trace_id / session_id	关联多轮
tool name + args（脱敏）	复盘选错工具
retrieval scores	调 k、阈值
prompt_version	与 eval 对齐

常见平台（选型维度）

平台	特点
LangSmith	LangChain 生态、数据集与 eval 一体
Langfuse	开源可自托管、SDK 轻
Helicone	网关层 log、成本聚合
OTel + Jaeger	与现有 APM 统一

原则：tracing 接在 Host 网关，不要每个 MCP Server 各写一套；Server 只回传结构化 result。

结构化追踪与告警

SLO 示例：p95 端到端 < 8s；tool 错误率 < 2%；无 citation 却声称「官方文档」= 0

• 对 无限 loop（tool 调用次数触顶）告警
• 对 单用户 QPS 限流，防 Agent 刷 API
• 日志 采样 生产全量；完整 trace 保留 7–14 天

与 ai-agents-essentials 的安全课一致：trace 里 不存 API key、完整信用卡号、原始 .env。

练习

• 为一轮 ReAct 画 span 树（至少 3 个节点）
• 列应脱敏的 3 类 tool 参数
• 写一条告警：连续 5 次 search_docs 空结果仍生成长答案

小结

可观测性让 Agent 从黑盒变成可调试系统；trace + eval 一起才能持续迭代。 下一课安全与合规，把追踪与权限、合规要求对齐。