LLM 与 AI Agent 可观测性
传统微服务常看请求量、错误率和耗时，到了 AI 应用里，也可以先用 Token、Error、Duration 建立一组基础指标；不过这三项只能说明服务有没有运行、花了多少钱、速度是否正常，还不能回答模型为什么给出了这个结果，更无法判断一次 HTTP 200 背后的答案是不是正确。
对普通 LLM 调用来说，一次请求已经可能包括 prompt 拼装、模型推理、内容清洗和结果返回；换成 LLM Agent / AI Agent 后，链路还会加入意图识别、RAG 检索、工具选择、参数构造、多次 LLM 调用与重试，因此真正需要建设的不是“多打一批日志”，而是让整条执行轨迹能够被还原、评分和归因。
1. 为什么传统 APM 还不够
传统 APM 擅长回答“哪里慢了”“哪里报错了”，但 AI Agent 会出现一些没有异常堆栈的失败，例如模型很自信地答错、选中了相似但不适用的工具、参数类型正确却语义错误，或者在几个工具之间来回循环，最终造成 token 和账单持续增长；这些现象在 HTTP 状态码上可能全部是成功，用户拿到的结果却不可用。
因此，AI Agent 可观测性至少要能回答下面几类问题：
- 一次任务内部执行过哪些步骤，每一步花了多少时间和 Token
- RAG 召回了哪些文档，排序和 score 是否合理，最终答案有没有使用这些证据
- Agent 选择了哪个工具，tool args 是否正确，调用顺序与依赖关系有没有被满足
- 最终输出是否准确、相关、完整，格式和安全要求有没有达到
- 失败发生在 Prompt、retrieval、Tool、LLM 还是 orchestration，能否复现到具体 span
- 单次请求、用户、组织和模型分别产生了多少成本，异常调用是否触发了熔断或 fallback
AgentTrace 将结构化轨迹分为 operational、cognitive、contextual 三类 surface，并把可观测性用于安全、可复现性、问责与实时监控；这类设计比单纯保存最终 input/output 更接近 Agent 的实际运行方式。
2. Trajectory 到底指什么
Trajectory 可以翻译成“轨迹、路径、运行过程”，在 LLM Agent / AI Agent 语境中，通常指 Agent 从收到任务到给出最终结果之间走过的完整行为路径，也就是 执行轨迹、任务轨迹 或 Agent 轨迹。
例如用户提出“帮我查一下某个法规，并总结适用条件”，Agent 可能会经历：
1. 接收用户问题
2. 判断用户意图：法规查询 + 条件总结
3. 改写检索 query
4. 调用知识库检索工具
5. 读取召回的法规条文
6. 判断哪些条文相关
7. 再次调用工具补充查询
8. 组织答案
9. 输出最终回答
这些步骤连在一起才构成一条 trajectory，其中 Trace 是运行追踪记录，Step 表示轨迹中的某一步，Tool Call 则是一次具体工具调用；trajectory evaluation 关注的是整条路径是否合理，不会只看最终答案是否碰巧正确。
| 检查对象 | 需要回答的问题 |
|---|---|
| 工具选择 | 工具是否选对，有没有调用不该使用的能力 |
| 参数构造 | 参数类型、值与约束是否正确 |
| 调用顺序 | 依赖步骤是否按合理顺序执行 |
| 中间结果 | 后一步有没有正确使用前一步结果 |
| 轨迹效率 | 是否存在多余步骤、重复调用或循环 |
| 最终输出 | 答案是否确实建立在前面得到的证据上 |
TRAJECT-Bench 也采用了这种轨迹级视角，除 final accuracy 外，还会检查 tool selection、argument correctness、dependency satisfaction 和 order satisfaction，这能把“答错了”进一步拆成可处理的具体原因。
3. 一套可落地的四层架构
Pockit 相关材料把 LLM Observability 分成 Instrumentation、Tracing、Evaluation、Dashboards 四层，这种划分也适合普通工程团队使用：
| 层级 | 作用 | 最低要求 |
|---|---|---|
| Instrumentation | 捕获 LLM 调用、RAG、工具与业务步骤 | 每个关键步骤都有 span |
| Tracing | 用 trace/span 还原执行树 | 一次请求能按时间顺序完整展开 |
| Evaluation | 判断结果与轨迹质量 | 不把 HTTP 成功当成任务成功 |
| Dashboards | 汇总质量、成本、延迟、SLA 和告警 | 能看趋势，也能下钻到原始 trace |
四层连接起来后，会形成一条研发闭环：
轨迹采集
-> 自动与人工评估
-> 失败归因
-> 修改 Prompt / Tool / RAG / orchestration
-> 回归测试
-> 发布新版本并继续采集
Phoenix 是 Arize AI 与开源社区维护的 AI observability and evaluation 工具，它基于 OpenTelemetry 与 OpenInference，能把模型调用、retrieval、tool use 和自定义逻辑放进 trace，也能在采集结果上继续做 Evaluation、Datasets & Experiments；工程上可以借鉴这种“Tracing 与 Evaluation 连在一起”的设计，而不是把两套数据割裂开来。Phoenix 文档
4. 轨迹数据怎样采集
4.1 用 trace/span 还原完整执行链
每次用户请求需要有一个 trace_id，内部步骤各自带 span_id，同时保留父子关系与时间顺序；这样出了问题以后，才能从 root span 一路展开到路由、RAG、工具调用和最终生成。
Trace: agent_run_xxx
├── 用户输入
├── 路由 / 意图识别
├── RAG 检索
│ ├── query
│ ├── top_k
│ ├── score
│ └── retrieved_docs
├── 工具调用
│ ├── tool_name
│ ├── tool_args
│ ├── tool_result
│ └── tool_latency
├── LLM 生成
│ ├── model
│ ├── prompt_tokens
│ ├── completion_tokens
│ ├── cost
│ └── latency
└── 最终输出
一份统一的 envelope schema 可以保存 UUID、surface type、trace ID、span ID、UTC timestamp 与结构化事件主体，字段稳定以后，日志、指标和评估结果才有机会通过同一个标识关联起来。
| Surface | 主要记录内容 |
|---|---|
| Operational Surface | 方法调用、参数与返回值摘要、状态、耗时和异常 |
| Cognitive Surface | 模型输入输出摘要、计划、反思、置信度与 token |
| Contextual Surface | HTTP API、数据库、缓存、向量库、文件系统和其他外部 I/O |
4.2 自动插桩与业务 span 一起使用
OpenTelemetry 或类似 SDK 可以自动捕获 LLM、HTTP、数据库、Redis、向量库等外部 I/O，不过自动插桩通常只能知道“某次调用发生了”，未必清楚它在业务上代表什么，所以仍需要手动增加语义明确的 span：
agent.route_intent
agent.retrieve_knowledge
agent.rerank_docs
agent.select_tool
agent.execute_tool
agent.generate_answer
agent.run_safety_check
agent.generate_followup_questions
AgentTrace、Phoenix 与 Arize 的相关设计都强调了结构化 tracing 的价值，区别只在于具体 schema 与产品实现；选型时可以复用 OpenTelemetry 生态，同时把 route、retrieve、rerank、safety check 等业务动作显式标出来。
4.3 采集不等于全量保存原文
model、token、latency、cost、状态码等 metadata 通常可以全量记录，但完整 prompt/completion、retrieved_docs 和 tool_result 可能包含个人信息、商业数据或系统提示，不适合无条件落库；embedding 向量与原始 API 响应的体积也很大，保存前应确认它们是否真的参与排查。
生产环境可以按数据敏感度采用脱敏、字段白名单、采样、分级权限与保留期限，例如完整 prompt/completion 只保存 10% 到 20% 作为分析样本，这个比例只是起点，最终仍要按照流量、成本、合规要求和故障复盘需要调整。
5. 应该统计哪些指标
5.1 性能、Token 与成本
耗时不能只看总延迟，流式生成至少还要区分 TTFT（Time to First Token）与 TPOT（Time Per Output Token），前者反映用户等待首个 token 的时间，后者更接近持续生成的速度与流畅度；吞吐率则用于判断模型服务能够同时支撑多少推理请求，这几项往往需要在延迟、并发和资源利用率之间作取舍。
| 指标 | 作用 |
|---|---|
| QPS / RPM、P50、P95、P99 | 观察流量与端到端延迟分布 |
| TTFT、TPOT、吞吐率 | 区分排队、首包和生成阶段 |
| Input Token / prompt tokens | 统计输入规模与输入侧成本 |
| Output Token / completion tokens | 统计生成规模与输出侧成本 |
| total tokens、单请求成本 | 找到上下文过长或循环调用 |
| user / org / model 成本 | 按用户、组织与模型核算账单 |
| LLM 调用次数、重试、fallback | 观察链路复杂度与依赖稳定性 |
Input Token 与 Output Token 可能采用不同定价，所以成本核算要分别统计；同一请求里有多次 LLM 调用时，还需要同时保留 span、trace、user 和 org 粒度，不能只看整站总量。
如果采用自托管推理，还要上报不同 GPU 卡的负载、显存、排队与错误情况，在单卡或单池扛不住时触发熔断、降级或路由到其他卡，避免一处过载把整条 Agent 链路拖慢。
5.2 RAG 检索
RAG 链路如果不可观测，答案出错后就很难区分模型幻觉与召回错误，至少要记录 query rewrite、top_k、score、doc_id、order 和实际进入 prompt 的内容范围。
| 指标 | 用途 |
|---|---|
| query rewrite 结果 | 检查用户意图有没有在改写时偏掉 |
| top_k 与 score 分布 | 判断召回范围和相似度质量 |
| doc_id、chunk 与 order | 复盘命中文档和 rerank 结果 |
| context token 占比 | 检查检索内容是否挤占过多上下文 |
| 空召回率、低分召回率 | 观察知识覆盖与低质量内容污染 |
| groundedness / faithfulness | 判断回答是否忠实使用了上下文 |
RAGAS 从 retrieval 与 generation 两部分评估 RAG，并提出 reference-free evaluation，可作为 groundedness、faithfulness、answer relevance 等指标的参考，不过生产判断仍应配合业务测试集和人工抽检。
5.3 工具调用
工具型 Agent 的风险不只在“调用报错”，工具选错、参数语义不对、先后顺序颠倒，都可能得到一份格式正常但业务错误的结果。
| 指标 | 说明 |
|---|---|
| tool selection accuracy | 是否选择了正确工具 |
| argument correctness | tool args 是否符合任务与 schema |
| dependency / order satisfaction | 多步调用是否满足依赖和顺序 |
| tool error rate / tool latency | 外部工具稳定性与耗时 |
| redundant tool calls | 是否存在没有价值的重复调用 |
| loop detection | 是否在同一组工具间循环 |
| unsafe tool call rate | 是否触发越权、高风险或未确认操作 |
这部分除了在线监控，还可以放进 CI 做 reference match；轨迹明确时采用 strict、unordered、subset、superset 等 trajectory match，允许多条合理路径时，则可用 LLM-as-Judge 按 rubric 判断调用是否合理。LangSmith 文档 与 AgentEvals 都提供了相近的工程方法。
Tool Selection Accuracy
Argument Correctness
Schema Adherence Rate
Tool Ambiguity Rate
Tool Redundancy Rate
Tool Error Recoverability
Unsafe Tool Call Rate
Tool Description Coverage
5.4 输出质量与轨迹质量
Tracing 负责说明“发生了什么”，Evaluation 才回答“做得好不好”，两部分不能互相替代；最小质量集可以先包含 accuracy、relevance、groundedness、format correctness 与 task success，其中 format correctness 可以检查 JSON、表格和字段结构，再根据业务风险增加 completeness、refusal correctness、hallucination rate 和 user satisfaction。
最终答案正确也不代表轨迹一定合理，Agent 可能绕过很多无关步骤，甚至使用错误中间信息后碰巧答对，因此还要观察轨迹长度、冗余步骤比例、中间决策正确率、依赖正确性、轨迹稳定性、goal fidelity 和行为合规性。
5.5 安全与确定性 Guards
下面这些规则不需要交给裁判员模型判断，可以对 100% trace 执行 deterministic guards：
单请求最大 token 数与最大成本
单用户每小时、单组织每日成本
单次 Agent 最大 LLM 调用次数
单次 Agent 最大工具调用次数
同一工具重复调用超限
总延迟超预算
空响应或格式错误
RAG 空召回或低分召回
工具异常率突然升高
敏感字段、越权工具或高风险写操作
LLM-as-Judge 的成本更高，也会受到位置偏差、冗长偏差和自我增强偏差影响，因此可以只对抽样 trace、告警样本与回归集运行，再通过人工标注定期校准；确定性规则适合守住硬边界，LLM-as-Judge 更适合处理相关性、完整性和轨迹合理性等软判断。
6. Prompt–Tool–Trajectory–Outcome 四层评估模型
目前没有一个框架能把 Agent 评估、Prompt 质量、Tool 设计、RAG 与业务结果全部覆盖，工程上可以把现有研究组合成 Prompt–Tool–Trajectory–Outcome 四层评估模型。
6.1 Prompt 质量
Prompt 质量不能只凭“读起来写得不错”判断，而要看它在任务集、扰动集和回归集上的表现是否稳定、可控、可解释。
| 评估维度 | 可参考的框架或工作 |
|---|---|
| 指令遵循、格式正确性 | OpenAI Evals、Promptfoo、G-Eval |
| 鲁棒性与 adversarial prompts | PromptRobust / PromptBench |
| LLM-as-Judge、CoT 与自定义 rubric | G-Eval、Prometheus |
| metric 驱动的 prompt pipeline 优化 | DSPy |
| 红队、安全与 CI/CD | Promptfoo、OpenAI Evals |
核心指标可以采用 Prompt Pass Rate、Instruction Following Score、Format Correctness、Robustness Score、Safety Violation Rate、Average Tokens per Prompt 与 Regression Failure Rate。
6.2 Tool 设计与调用
Agent 失败不一定是模型能力不足，也可能是 Tool Schema 过于模糊、参数太复杂、工具粒度过大或错误信息无法让模型继续处理。
| 评估维度 | 需要检查的内容 |
|---|---|
| 工具命名与 description | 用途、边界和限制是否说清楚 |
| 参数 schema | 类型、必填项、枚举与约束是否明确 |
| 工具粒度 | 是否只完成一类清晰动作，避免过大或过碎 |
| 返回结构 | 是否便于后续步骤稳定读取 |
| 错误反馈 | 参数错、权限错、无结果时能否恢复 |
| 安全边界 | 删除、支付和其他写操作是否需要确认与权限 |
API-Bank、ToolLLM / ToolBench、Gorilla / BFCL、ToolAlpaca 更偏工具选择、API retrieval、API calling、function calling 与参数生成，其中 BFCL 还使用 AST 等方式检查调用正确性，ToolEmu 关注高风险工具和安全评估；OpenAI Function Calling / Structured Outputs 则能为 Tool Schema 与结构化输出约束提供工程参考。
6.3 Agent 轨迹
这一层把 route、retrieve、tool call、final answer 连成完整路径，指标包括 Trajectory Match Score、Tool Order Accuracy、Dependency Satisfaction Rate、Redundant Step Rate、Step-level Success Rate、Trajectory Efficiency 和 Failure Attribution Label。
TRAJECT-Bench 适合支持细粒度工具轨迹评估，LangSmith Trajectory Evals / AgentEvals 能用于 trajectory match 与 LLM-as-Judge，AgentTrace 则说明结构化 operational / cognitive / contextual trace 为什么是后续评估的基础。
6.4 Outcome 与业务结果
最终输出仍然要评估，只是不能把它当成唯一指标；常见维度有任务成功率、答案准确性、groundedness、用户体验、成本、延迟和回归稳定性，AgentBench、WebArena、GAIA、SWE-bench 分别提供了 LLM-as-Agent 多环境交互、网页任务、通用 AI Assistant 与真实 GitHub issue、PR 场景的参考，相比单轮 QA，它们更接近完整任务。
7. 建设到什么程度才算够
7.1 MVP：线上问题可以复盘
系统刚开始建设时，不用立刻做一套完整平台，先保证出错以后可以从 trace 还原 Agent 做过什么：
每次请求都有 trace_id
每次 LLM 调用记录 model、tokens、latency、cost
每次工具调用记录 tool_name、args、result、latency
每次 RAG 记录 query、top_k、score、doc_id、order
最终输出与异常可以追踪
成本能够按 span / trace / user / org 聚合
7.2 生产可用：异常可以主动告警
到了生产阶段，不能再完全依赖事后手动查 trace，需要给 token、成本、调用次数、循环、延迟、空响应、格式错误、RAG 空召回和工具异常率设置 guard 与告警；告警卡片最好能直接跳到对应 trace，而不是只给出一个聚合数字。
7.3 成熟阶段：评估结果进入研发闭环
成熟的 AI Agent 可观测性会把低分 trace、失败轨迹、人工反馈和 LLM-as-Judge 结果沉淀成数据集，自动完成失败归因与回归评估，再用它们修改 Prompt、Tool、RAG 和 Agent 编排。
线上 trace
-> 自动评分
-> 低分样本入库
-> 失败归因
-> 修改 Prompt / Tool / RAG / orchestration
-> 回归评估
-> 发布
ETO、AgentTrek、T-PRA 等工作把轨迹进一步用于 Agent 优化，其中 ETO 会利用探索得到的成功/失败轨迹对并结合 DPO 训练，T-PRA 相关材料则从 Actor、Advisor、Critic 与长期目标的角度讨论序列决策；这些工作说明 trajectory 不只是一份排查日志，还能成为训练和优化数据。ETO AgentTrek
8. 相关论文与工程框架怎样分工
原始资料中出现了 Survey、AgentTrace、Pockit、Phoenix、Arize、TRAJECT-Bench、LangSmith、AgentEvals、ETO、AgentTrek、T-PRA 等不同类型的内容，它们不属于同一个层次，放在一起时可以按用途归类：
这些资料分散在 arXiv、OpenReview、ACL Anthology、GitHub 与 LangChain 文档中，引用时要区分论文、benchmark、开源实现和产品说明，避免把工程功能直接当作学术结论。
| 方向 | 代表工作或框架 |
|---|---|
| 可观测性与结构化轨迹 | AgentTrace、Pockit、Phoenix、Arize、OpenTelemetry、OpenInference |
| Agent 任务环境 | AgentBench、WebArena、GAIA、SWE-bench |
| Agent 轨迹评估 | TRAJECT-Bench、LangSmith Trajectory Evals、AgentEvals |
| Prompt 评估 | PromptRobust / PromptBench、G-Eval、MT-Bench / Chatbot Arena、Prometheus、DSPy、OpenAI Evals、Promptfoo |
| Tool / API 评估 | API-Bank、ToolLLM / ToolBench、Gorilla / BFCL、ToolAlpaca、ToolEmu、OpenAI Function Calling / Structured Outputs |
| RAG 评估 | RAGAS |
| 轨迹优化 | ETO、AgentTrek、T-PRA、DPO |
这张表也说明了为什么很难找到一套“完整统一标准”，现有 benchmark 与工程框架分别覆盖任务、轨迹、Prompt、Tool、RAG、质量或安全中的某一部分，更实际的做法是根据产品风险建立自己的分层指标，再用统一 trace 把它们连起来。
如果需要把它写进系统设计文档，还可以再分成四个实现层：评估对象包含 Prompt、Tool Schema、Agent Trajectory、Final Output 和 Business Outcome；评估方法包括 Deterministic Check、Reference Match、LLM-as-Judge、Human Review、Online Feedback 与 Regression Test；评估指标再按 Prompt、Tool、Trajectory、Output、Cost / Latency 分组，得到结果后进入闭环优化层。
9. 小结
AI Agent 可观测性可以归纳为三个层次：一是 能看见，也就是通过 trace 还原 LLM、RAG、工具、异常、Token、成本和延迟；二是 能判断，对答案质量、证据使用、工具选择、参数与调用顺序进行评估；三是 能改进，把低质量 trace、失败轨迹与人工反馈放进回归、归因和优化闭环。
只有 Token、Error、Duration 时，我们能知道系统花了多少资源，却未必知道它为什么做错；把 Trajectory、Evaluation 与 Outcome 接上以后，执行轨迹才会真正成为可追踪、可评分、可归因、也能继续用于优化的数据资产。