agent-observability

Agent 可观测性：用 trace/span 记录每一步、工具调用、token 和成本

补充说明

Agent 的一次运行包含多次模型调用、工具调用、检索和状态转换，传统日志很难还原。可观测性要把一次运行串成 trace，每个步骤是一个 span，记录输入、输出、耗时、token、成本、错误和关键属性（用户、会话、工具名、模型版本）。OpenTelemetry 的 GenAI 语义约定正在成为通用标准。

可观测性不仅用于排障，也用于评估和成本治理：找出哪一步最慢、哪个工具最贵、哪类请求失败率最高。记录时要脱敏，避免把 prompt 中的个人信息、密钥和业务数据写进日志。

常用示例

# 伪代码：一次 Agent 运行的 trace 结构
with tracer.start_as_current_span("agent.run") as run:
    run.set_attribute("agent.name", "support")
    run.set_attribute("user.id_hash", hash_user(user.id))

    with tracer.start_as_current_span("llm.chat") as span:
        span.set_attribute("gen_ai.request.model", "gpt-4o-mini")
        span.set_attribute("gen_ai.usage.input_tokens", resp.usage.prompt_tokens)
        span.set_attribute("gen_ai.usage.output_tokens", resp.usage.completion_tokens)

    with tracer.start_as_current_span("tool.search_docs") as span:
        span.set_attribute("tool.name", "search_docs")
        span.set_attribute("tool.args.query", redact(query))
        span.set_attribute("tool.result.count", len(results))

# Langfuse：记录生成、工具和评分
from langfuse import Langfuse
langfuse = Langfuse()

trace = langfuse.trace(name="support-agent", user_id=user.id)
generation = trace.generation(
    name="answer", model="gpt-4o-mini",
    input=messages, output=answer,
    usage={"input": 1200, "output": 300},
)
trace.score(name="user_feedback", value=1)

必须记录的字段：
- trace_id / session_id / user_id（脱敏/哈希）
- 每步类型（llm/tool/retrieval）、耗时、状态、错误
- 模型名/版本、token、成本
- 工具名、参数摘要（脱敏）、结果条数
- 检索命中的文档 ID/分数（不记录全文）
- 评估分数、人工反馈、是否触发审批

易错点与排错

• 只记录最终输出：无法定位是哪一步慢/错；必须按步骤建 span。
• 记录完整 prompt：可能含个人信息/密钥；脱敏、截断、按字段白名单记录。
• 没有工具 span：Agent 最常出问题的是工具调用；工具参数、结果、耗时都要记。
• trace 爆炸：高流量全量记录成本高；采样 + 错误全量 + 关键用户全量。
• 没有版本维度：模型/prompt/工具升级后无法对比；记录版本和配置哈希。
• 只做日志不做分析：没有看板、告警和回放；至少要有失败率、P95、成本趋势。
• 供应商锁定：用 OpenTelemetry 等标准导出，保留原始数据能力。
• 忽略成本：token 和工具调用费用要按 trace 聚合，才能做预算和优化。

相关命令

• langfuse — LLM 追踪、评估与成本。
• phoenix — Arize Phoenix 追踪与评估。
• langsmith — LangChain 生态追踪。
• openai-agents-sdk — Agent SDK 与 tracing。
• agent-memory — 记忆读写也要纳入追踪。

参考链接

• OpenTelemetry GenAI 语义约定
• Langfuse 文档
• Arize Phoenix 文档

读完自测

合上页面，先回答，再展开对照。

1. trace 和 span 的关系是什么？
2. Agent 可观测性必须记录哪些关键字段？
3. 为什么不能把完整 prompt 直接写进日志？