【学习笔记】Agent 可观测性——看见你的 Agent 在想什么-12/15

这篇讲一个随之而来的问题当你的 Agent或多个 Agent在生产中跑起来出了问题你怎么知道哪里错了一、为什么 Agent 可观测性比传统可观测性更难传统服务的可观测性模型很成熟函数调用有确定的输入输出异常有 stack trace性能有 latency 分布错误有 HTTP status code。出了问题日志 指标基本能定位。Agent 的问题在于执行路径是非确定性的。同样的输入Agent 可能走完全不同的推理路径调用不同的工具产生不同的中间结果最终到达或没到达正确答案。传统的「输入→处理→输出」三段式在 Agent 这里变成了「输入→推理循环 N 轮→工具调用 M 次→可能的答案」。具体难点1.1推理不透明模型内部的推理过程不是显式的函数调用是 token 序列。你看到的是最终文本不是推理步骤。1.2 工具调用链Agent 调用工具 A结果作为输入调用工具 BB 的结果触发调用工具 C——这个链路可能有 10-20 步每一步都可能出错错误还可能是级联的A 的轻微偏差导致 C 的完全失败。1.3 概率性失败同一任务重跑可能成功。这让传统的「复现 bug → 修复 → 验证」工作流完全失效。你不能稳定复现就很难确认修复是否有效。1.4 多Agent 时序上一篇的多 Agent 场景里Agent A 和 Agent B 并行执行共享状态时序依赖——这类问题在传统分布式系统里已经够难了加上 LLM 的非确定性难度再上一层。二、重新定义可观测性三支柱传统可观测性的三支柱Traces、Metrics、Logs在 Agent 时代需要重新定义其含义。2.1 Traces推理-工具调用链路追踪传统Trace 追踪的是函数调用栈——A 调 B 调 C每层的耗时和参数。Agent Trace 追踪的是推理-行动序列Agent 收到任务 (t0) ├── LLM 推理 (t0~2.3s) ← 模型在想什么 │ 思考需要先了解代码库结构用 glob 搜索 ├── Tool Call: Glob(**/*.py) (t2.3~2.8s) │ 输入: pattern**/*.py │ 输出: [128 个文件路径] ├── LLM 推理 (t2.8~5.1s) │ 思考文件太多聚焦 src/ 目录 ├── Tool Call: Read(src/auth/jwt.py) (t5.1~5.4s) │ 输入: file_pathsrc/auth/jwt.py │ 输出: [文件内容 847 tokens] ├── LLM 推理 (t5.4~9.2s) │ 思考发现问题JWT 密钥硬编码 └── 最终答案生成 (t9.2~11.0s)这个 Trace 让你看到推理花了多少时间、工具调用了多少次、每次工具的输入输出是什么、在哪个步骤出错了。2.2 Metrics超越延迟和错误率传统 Metrics 关注延迟p50/p95/p99、错误率、吞吐量。Agent Metrics 还需要关注Token 使用输入 token、输出 token、缓存命中率——这直接决定成本工具调用次数平均完成任务需要调用多少次工具趋势是否在上升任务完成率Agent 成功完成任务的比例不是「没报错」是「真的完成了」重试次数Agent 需要重试多少次才能成功上下文使用率任务结束时上下文窗口用了多少——持续接近上限是问题信号成本/任务每完成一个任务花了多少钱趋势如何2.3 Logs模型输入输出完整记录传统日志记录应用层事件。Agent 日志需要记录完整的模型输入系统提示 对话历史——方便复现和调试完整的模型输出包括思考过程如果模型支持工具调用参数和返回值——每一次完整记录Token 计数和成本——每次 LLM 调用错误详情——工具失败、模型拒绝、上下文溢出三、主流可观测性平台对比3.1 LangSmithLangChain 官方的可观测性平台。如果你用 LangChain/LangGraph 生态LangSmith 的集成几乎是零成本import os os.environ[LANGCHAIN_TRACING_V2] true os.environ[LANGCHAIN_API_KEY] ... # 之后所有 LangChain/LangGraph 调用自动追踪 # 不需要修改任何业务代码核心优势近零接入成本环境变量打开自动追踪原生 LangChain 集成追踪粒度精确到每个 Chain、每个 Tool、每个 LLM 调用数据集和评估可以把实际运行的 trace 导出为评估数据集直接用来跑评估适合场景LangChain/LangGraph 技术栈或者需要快速上手可观测性的团队。3.2 Arize AI企业级 AI 可观测性平台覆盖从 LLM 到完整 Agent 工作流。核心优势Span 级追踪精确追踪到每个操作的 Span支持分布式 Agent 追踪Phoenix开源部分Arize 的开源追踪工具基于 OpenTelemetry可以自托管漂移检测监控模型行为随时间的漂移——相同输入输出质量是否在下降企业特性SSO、RBAC、数据留存、合规报告适合场景有合规要求的企业或者需要长期监控模型行为漂移的团队。3.3 Langfuse开源的 LLM 可观测性平台可以完全自托管from langfuse import Langfuse from langfuse.decorators import observe, langfuse_context langfuse Langfuse() observe() # 装饰器自动追踪这个函数 def run_agent(task: str) - str: # 你的 Agent 逻辑 result agent.run(task) # 手动记录评估结果 langfuse_context.score_current_observation( nametask_completion, value1 if task_completed else 0 ) return result核心优势自托管数据留在自己的基础设施适合数据敏感场景成本透明开源自托管几乎零平台费用灵活评估内置 LLM-as-Judge 评估可自定义评估维度适合场景数据隐私要求高不能把数据发给第三方 SaaS、或者需要控制可观测性平台成本的团队。3.4 Galileo定位是「评估 护栏 可观测性」一体化特别强调质量评估内置评估指标幻觉率、忠实度、相关性——不需要自己写评估逻辑护栏集成发现问题可以直接触发护栏拦截、告警、降级实时监控生产环境实时监控质量指标不只是 trace 存档适合场景需要对 Agent 输出质量做持续监控或者要把可观测性和护栏系统统一的团队。3.5 平台选择速查场景推荐用 LangChain/LangGraph快速上手LangSmith数据不出境自托管Langfuse企业合规、漂移检测Arize AI质量监控 护栏一体Galileo四、OpenTelemetry for LLMs新兴标准传统可观测性领域OpenTelemetryOTel已经成为事实标准——统一的 Trace/Metric/Log 数据格式各平台都兼容。LLM 可观测性正在走同样的路。OpenLLMetryTraceloop 主导是目前最成熟的 OTel for LLMs 实现定义了 LLM span 的标准属性from opentelemetry import trace from opentelemetry.sdk.trace import TracerProvider # 标准化的 LLM Span 属性 span.set_attribute(llm.vendor, anthropic) span.set_attribute(llm.request.model, claude-opus-4-7) span.set_attribute(llm.request.max_tokens, 4096) span.set_attribute(llm.usage.prompt_tokens, 1247) span.set_attribute(llm.usage.completion_tokens, 382) span.set_attribute(llm.usage.total_tokens, 1629) span.set_attribute(llm.response.model, claude-opus-4-7)标准化的意义写一次 instrumentation数据可以同时发给 LangSmith、Langfuse、Arize——不被任何一家平台绑定。Anthropic 的官方 SDK 正在逐步支持 OTel 标准。如果你现在开始搭可观测性基础设施建议用 OTel 作为底层上层再选择展示和分析平台。五、生产典型组合单一平台往往不能满足所有需求。生产中常见的双层组合5.1 网关层成本追踪 分析层质量监控Helicone / Portkey作为 LLM 网关所有 LLM 调用经过网关自动记录 Token 用量和成本支持按 Key/用户/任务类型做成本归因还能做请求缓存相同请求直接返回缓存结果省钱# Helicone 接入只需要替换 base_url import anthropic client anthropic.Anthropic( base_urlhttps://anthropic.helicone.ai, default_headers{ Helicone-Auth: fBearer {HELICONE_API_KEY}, Helicone-Property-Task: code-review, # 自定义属性用于成本归因 } ) # 之后所有调用自动被 Helicone 记录5.2 Langfuse / LangSmith作为追踪和评估层完整的 Trace 记录、质量评估、失败分析。两层分工网关层专注成本和流量追踪层专注质量和调试不互相耦合。六、调试 Agent 失败的实战方法有了可观测性基础设施调试 Agent 失败就有了具体的工作流6.1 定位上下文腐烂「上下文腐烂」是 Agent 长时间运行后常见的失败模式——随着对话历史积累早期的关键信息被淹没Agent 开始给出矛盾或错误的结果。用 Trace 定位找到任务开始走偏的那个 LLM 调用查看那一刻的完整上下文。通常能看到上下文里充斥着大量已完成步骤的结果原始任务描述占比很小信噪比极低。修复方向增加 Compaction 频率或者在任务超过一定步数时主动重注入原始任务描述第 4 篇讲过这个模式。6.2 追踪工具调用链中的错误传播Agent 的最终答案是错的但不知道从哪一步开始偏的——用 Trace 逐步展开工具调用链Step 1: Glob(**/*.ts) → 返回了 247 个文件 ✓ Step 2: Read(src/config/database.ts) → 返回了文件内容 ✓ Step 3: LLM 推理 → 数据库连接字符串在 config.host ← 这里出错了 实际上 config 对象结构不是这样的 Step 4: 基于错误假设继续推理 → 级联错误找到 Step 3 的 LLM 推理查看当时的输入——问题通常是上下文提供的信息不足以让模型做出正确推断或者模型对不熟悉的代码库结构做了错误假设。6.3 复现概率性失败这是最难的部分。同一任务跑 5 次有 2 次失败你无法稳定复现。实用方法从失败的 Trace 里导出完整的模型输入系统提示 对话历史 当前 prompt用这个完整输入直接调用模型看是否能复现失败如果能复现在固定输入上做调试调整系统提示、增加上下文、换模型如果不能复现真正的概率性在相同输入上多次调用统计失败率评估是否需要修复Langfuse 和 LangSmith 都支持从 Trace 直接导出「Playground 可用」的格式简化这个过程。七、实战为 Agent 搭建可观测性基础设施一个适合大多数项目的最小可观测性配置Step 1接入 Langfuse5 分钟pip install langfuseimport os os.environ[LANGFUSE_PUBLIC_KEY] pk-... os.environ[LANGFUSE_SECRET_KEY] sk-... os.environ[LANGFUSE_HOST] https://cloud.langfuse.com # 或自托管地址 from langfuse.decorators import observe observe() def your_agent_function(task: str) - str: # 你的 Agent 逻辑不需要任何改动 return resultStep 2添加关键 Metrics10 分钟from langfuse.decorators import observe, langfuse_context observe() def run_agent_task(task: str) - dict: start_time time.time() try: result agent.run(task) success validate_result(result) # 记录任务级别的评估结果 langfuse_context.score_current_trace( nametask_success, value1 if success else 0, commentf耗时: {time.time() - start_time:.1f}s ) return {success: success, result: result} except Exception as e: langfuse_context.score_current_trace( nametask_success, value0, commentf错误: {str(e)} ) raiseStep 3设置成本告警用 Helicone 或 Langfuse 的内置预算功能设置每日/每周 Token 用量上限超限发告警。防止 Agent 出 Bug 时默默烧掉大量 API 费用。Step 4建立失败分析工作流每周 review 失败的 Trace任务完成率低于 90%找最常见的失败步骤某类任务的 Token 用量异常高找上下文膨胀的位置错误集中在特定工具检查工具的描述或实现可观测性的价值不在于数据收集本身在于建立「发现问题 → 定位 → 修复 → 验证」的闭环。八、可观测性是 Harness 的眼睛这个系列讲了很多 Harness 的主动控制手段——上下文管理、安全护栏、多 Agent 编排。可观测性是 Harness 的另一面被动但同样关键。主动控制决定 Agent 怎么运行可观测性告诉你 Agent 实际在怎么运行——两者的差距就是你需要持续改进的地方。没有可观测性你是在黑盒里调 Agent。有了可观测性你才真正拥有这个系统。参考文献Agent 可观测性——看见你的 Agent 在想什么