适合前后端/测试等有编程基础的同学手把手教你让Agent在线上“裸奔”变“透明”前言通过前面20节课的学习你已经能把Agent打包成生产级服务、部署到Kubernetes、扛住并发请求了。它在线上跑得飞起用户开始用起来了。然后凌晨2点你被一通电话吵醒——“Agent好像疯了一直在调用工具已经跑了5分钟还没停……”你爬起来打开日志看到几百行乱七八糟的输出打开数据库发现某个表被查了几百次打开云厂商控制台看到API费用在疯狂飙升。你完全不知道Agent刚才做了什么、为什么这么做、该怎么修。这就是没有可观测性的后果。一句话定义Agent的可观测性是通过日志Logs、追踪Traces、指标Metrics三大支柱对Agent的每一次推理、每一个工具调用、每一轮决策进行结构化采集和分析让你能回答“Agent做了什么、为什么这么做、结果怎么样”的系统性能力。Agent的可观测性不是“锦上添花”而是生产环境的刚需。全文约8500字包含完整可运行的代码。一、为什么Agent的可观测性如此不同1.1 传统软件 vs AI Agent调试对象的根本变化在传统软件中调试是线性的、确定的代码出Bug → 看错误日志 → 找堆栈跟踪 → 定位出错的代码行 → 修复 → 上线但AI Agent完全不同当Agent用200步、耗时2分钟完成一个任务在中间某一步出错了——没有堆栈跟踪因为没有“代码”出错。出错的是Agent的推理。你要回答的是这样的问题为什么Agent在第23步选择了edit_file而不是read_file当时Agent看到了什么上下文和Prompt指令在这2分钟、200步的执行轨迹中Agent是从哪一步开始“跑偏”的传统追踪工具回答不了这些问题。1.2 Agent可观测性的三大独特挑战挑战说明后果故障隐藏在执行轨迹中Agent可能选错工具、检索错文档、陷入死循环但仍能输出一个“看似合理”的最终答案用户报告问题之前你可能完全不知道Agent自己决定花多少钱Agent自主决定调用多少次模型、执行多少个工具成本是动态的一个失控的Agent可能几分钟内烧掉你一个月的预算执行轨迹极长长期运行的Agent可能产生包含成百上千个观察节点的trace人类无法手工翻阅需要结构化的搜索和聚合能力1.3 可观测性三大支柱Logs Traces Metrics┌─────────────────────────────────────────────────────────────────┐ │ 可观测性三大支柱 │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Logs │ │ Traces │ │ Metrics │ │ │ │ 日志 │ │ 追踪 │ │ 指标 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ ↓ ↓ ↓ │ │ “发生了什么” “为什么发生” “发生了多少” │ │ 结构化事件记录 完整调用链路 聚合统计数据 │ │ 错误/警告/信息 每步的输入输出 延迟/吞吐/错误率 │ │ │ │ 三者结合 → 回答Agent做了什么、为什么这么做、效果怎么样 │ └─────────────────────────────────────────────────────────────────┘二、核心工具一LangSmith —— LangChain官方可观测平台2.1 什么是LangSmithLangSmith是LangChain团队构建的LLM应用可观测性平台专为捕获、调试、评估和监控LLM应用行为而设计。使用LangSmith的Agent自动支持追踪——所有用create_agent构建的Agent无需额外代码即可获得完整的可观测能力。2.2 快速启用LangSmith追踪只需设置三个环境变量exportLANGSMITH_TRACINGtrueexportLANGSMITH_API_KEYyour-langsmith-api-keyexportLANGSMITH_PROJECTmy-production-agent# 可选指定项目名然后正常运行你的Agent代码所有步骤都会被自动记录到LangSmith。2.3 LangSmith能追踪什么数据类型说明完整trace树从用户输入到最终输出的每一步工具调用Agent选择了哪个工具、传入了什么参数、返回了什么结果LLM调用每次调用的prompt、completion、model参数、token用量决策点Agent在每个步骤的推理和选择成本自动记录token消耗和费用中间步骤Agent的完整思考轨迹2.4 LangSmith Engine自动故障诊断LangSmith不只是“看板”它还能主动帮你修BugLangSmith Engine会监视你的生产trace将故障聚类为命名问题诊断根因并自动提交包含修复方案的PR。这意味着从“发现问题 → 定位原因 → 修复上线”的闭环可以被大幅缩短。2.5 选择性追踪与精细化控制不是所有调用都需要追踪。你可以用tracing_context精确控制哪些部分被追踪fromlangchain_core.tracersimportLangChainTracer# 只追踪特定调用tracerLangChainTracer()# 这个调用会被追踪awaitagent.invoke({messages:[{role:user,content:重要请求}]},{callbacks:[tracer]})# 这个调用不会被追踪如果LANGSMITH_TRACING未设置awaitagent.invoke({messages:[{role:user,content:普通请求}]})三、核心工具二LangFuse —— 开源LLM可观测平台3.1 什么是LangFuseLangFuse是一个开源的LLM工程平台提供追踪、评估、Prompt管理和数据集实验等能力。与LangSmith的核心区别维度LangSmithLangFuse开源❌ 闭源SaaS✅ 开源可自托管数据主权数据在LangChain云端数据在你自己的基础设施中定价按量付费开源版免费企业版付费Agent支持✅ 原生深度集成✅ 通过CallbackHandler集成3.2 快速集成LangFuse安装pipinstalllangfuse集成到LangChain/LangGraphfromlangfuse.callbackimportCallbackHandlerfromlangchain.agentsimportcreate_agentfromlangchain_openaiimportChatOpenAI# 1. 初始化LangFuse Handlerlangfuse_handlerCallbackHandler(public_keypk-lf-xxx,secret_keysk-lf-xxx,hosthttps://cloud.langfuse.com# 或自托管地址)# 2. 创建AgentllmChatOpenAI(modeldeepseek-v4-flash)agentcreate_agent(modelllm,tools[...])# 3. 带追踪执行resultagent.invoke({messages:[{role:user,content:...}]},{callbacks:[langfuse_handler]})3.3 LangFuse的Agent专用功能LangFuse在2025年11月加入了Agent Graphs功能能从观测的时间与嵌套中推断图结构直观展示多步Agent的执行流程。支持的10种观测类型类型说明event通用事件span时间段generationLLM生成agentAgent步骤tool工具调用chainChain执行retriever检索步骤evaluator评估embedding向量化guardrail安全护栏3.4 observe()装饰器追踪自定义逻辑对于LangChain之外的自定义逻辑如数据清洗、API格式化可以用observe()装饰器自动追踪fromlangfuse.decoratorsimportobserveobserve()defpreprocess_user_input(raw_text:str)-str:# 自定义预处理逻辑returncleaned_textobserve()defformat_agent_output(raw_output:str)-dict:# 自定义格式化逻辑return{result:raw_output,format:json}四、开放标准OpenTelemetryOTel4.1 为什么需要OpenTelemetryLangSmith和LangFuse都是优秀的工具但它们各自有各自的SDK和API。如果有一天你想从LangSmith切换到LangFuse或者同时使用多个后端怎么办OpenTelemetryOTel就是答案——它是一个开放标准让你用一套API采集遥测数据然后发送到任意支持OTel的后端。4.2 OTel SigNoz开源可观测性栈SigNoz是一个开源的APM应用性能监控工具原生支持OpenTelemetry。安装依赖pipinstallopentelemetry-distro\opentelemetry-exporter-otlp\openinference-instrumentation-langchain\langchain langgraph自动instrumentationopentelemetry-bootstrap--actioninstall配置并运行fromlangchain.agentsimportcreate_agent agentcreate_agent(modeldeepseek-v4-flash,tools[...])# 所有调用会自动通过OTel采集并发送到SigNozresultagent.invoke({messages:[{role:user,content:...}]})4.3 OTel Grafana Cloud企业级可观测性Grafana Cloud也提供了针对AI Agent的预构建仪表板可分析响应时间、错误率、吞吐量和Token用量。4.4 阿里云LoongSuiteOTel GenAI语义规范阿里云基于OTel社区标准推出了LoongSuite GenAI可观测语义规范并提供了无侵入采集方案让Agent实现“可看见、可分析、可审计、可治理”。五、监控什么—— Agent核心指标体系5.1 性能指标Performance Metrics这些指标告诉你Agent跑得有多快、有多稳指标说明告警建议延迟P50/P90/P99追踪所有三个百分位P99揭示平均延迟隐藏的“长尾”问题P99 30s 告警吞吐量Throughput按会话级别测量每秒请求数而非仅按LLM调用突降50%告警每会话Token消耗高Token数意味着失控的推理循环或低效的Prompt构造单会话 100k tokens 告警迭代次数每个会话的循环迭代次数 25次触发人工介入工具调用频率/失败率Agent调用工具的次数和失败比例失败率 10%告警5.2 质量指标Quality Metrics这些指标告诉你Agent回答得好不好指标说明评估方式幻觉频率Agent输出中包含未被检索上下文支持的主张的频率LLM-as-Judge接地性与相关性检索到的chunk是否真正支持最终答案人工/LLM评估检索精确率Agent在“噪声上下文”中工作的比例规则/LLM评估5.3 成本与安全指标Cost Safety Metrics这些指标是大多数团队最容易忽视的但恰恰是最重要的指标说明告警建议Turn预算限制每个会话的迭代次数防止失控和无限循环达到80%预算告警成本断路器设置会话级成本上限在单个失控会话耗尽预算前停止执行超过预算阈值自动熔断Token用量按项目、按用户、按模型维度聚合日环比增长 50%告警六、成本监控让每一分钱都花得明明白白6.1 LangSmith成本追踪LangSmith自动记录主流LLM提供商的token用量和成本并提供统一视图。在LangSmith UI中查看成本的三种方式方式说明Trace树内每个运行节点的详细token和成本明细项目统计项目内所有trace的汇总token和成本仪表板成本和token用量随时间变化的趋势成本归因维度# LangSmith支持按运行类型归类成本# 你可以查询LLM调用花了多少钱、Retriever花了多少钱、Tool调用花了多少钱# 这让你清楚地知道管道中哪个组件消耗了最多的token和成本6.2 LangFuse成本告警LangFuse提供可配置阈值的支出告警当成本超过设定阈值时自动通知。6.3 手动上报自定义成本对于非LLM组件如外部API调用、向量数据库查询可以手动上报成本fromlangsmithimporttraceabletraceable(run_typetool)defcall_external_api(query:str):# 执行外部调用resultrequests.post(https://api.example.com/search,json{q:query})# 手动上报成本# 在当前run上附加成本数据returnresult.json()七、实战为生产Agent配置完整可观测性7.1 三层可观测性架构┌─────────────────────────────────────────────────────────────────┐ │ 三层可观测性架构 │ │ │ │ 第一层Agent框架层自动 │ │ ├── LangSmith Tracing所有Agent自动支持 │ │ └── 自动记录工具调用、LLM调用、决策点、token用量 │ │ │ │ 第二层自定义业务层手动 │ │ ├── observe() / traceable 装饰自定义逻辑 │ │ └── 记录业务指标、用户反馈、领域特定事件 │ │ │ │ 第三层基础设施层OTel │ │ ├── OpenTelemetry采集系统级指标 │ │ └── 记录CPU、内存、网络、数据库连接池 │ └─────────────────────────────────────────────────────────────────┘7.2 完整代码示例importosfromlangchain.agentsimportcreate_agentfromlangchain.toolsimporttoolfromlangchain_openaiimportChatOpenAIfromlangfuse.callbackimportCallbackHandlerfromlangfuse.decoratorsimportobserve# 1. 配置LangSmith os.environ[LANGSMITH_TRACING]trueos.environ[LANGSMITH_API_KEY]your-langsmith-keyos.environ[LANGSMITH_PROJECT]production-agent# 2. 配置LangFuse langfuse_handlerCallbackHandler(public_keypk-lf-xxx,secret_keysk-lf-xxx,hosthttps://cloud.langfuse.com)# 3. 定义工具带自定义追踪 toolobserve()# LangFuse自动追踪defget_weather(city:str)-str:获取城市天气returnf{city}晴25°Ctoolobserve()defsearch_database(query:str)-str:搜索内部知识库# 模拟数据库查询returnf找到关于{query}的3条记录# 4. 自定义业务逻辑追踪 observe()defpreprocess_query(raw:str)-str:预处理用户输入returnraw.strip().lower()observe()defpostprocess_response(raw:str)-dict:后处理Agent输出return{content:raw,length:len(raw),timestamp:2026-08-20T10:00:00Z}# 5. 创建Agent llmChatOpenAI(modeldeepseek-v4-flash,temperature0.3)agentcreate_agent(modelllm,tools[get_weather,search_database],system_prompt你是一个智能助手可以查询天气和搜索知识库)# 6. 执行带多层可观测性 defrun_agent_with_observability(user_query:str):# 预处理被observe追踪processedpreprocess_query(user_query)# Agent执行LangSmith自动追踪 LangFuse手动追踪resultagent.invoke({messages:[{role:user,content:processed}]},{callbacks:[langfuse_handler]}# LangFuse追踪)# 后处理被observe追踪finalpostprocess_response(result[messages][-1].content)returnfinal# 测试responserun_agent_with_observability(北京天气怎么样)print(response)7.3 可观测性检查清单检查项工具状态✅ Agent每一步的traceLangSmith / LangFuse自动✅ 工具调用记录LangSmith / LangFuse自动✅ Token用量和成本LangSmith / LangFuse自动✅ 自定义业务逻辑observe / traceable手动添加✅ 延迟百分位P50/P90/P99Prometheus Grafana需配置✅ 错误率和告警Prometheus AlertManager需配置✅ 会话级成本断路器自定义中间件需实现✅ 用户反馈采集LangSmith / LangFuse需配置八、最佳实践与常见陷阱8.1 生产环境可观测性最佳实践① 分层采集各司其职层级采集内容工具Agent框架层trace、工具调用、LLM调用LangSmith/LangFuse业务逻辑层自定义事件、用户反馈observe装饰器基础设施层CPU、内存、网络OpenTelemetry Prometheus② 设置成本断路器# 在Agent执行前检查成本MAX_COST_PER_SESSION1.0# 美元defcheck_cost_budget(current_cost:float):ifcurrent_costMAX_COST_PER_SESSION:raiseException(f成本超限${current_cost} ${MAX_COST_PER_SESSION})③ 主动监控而非被动响应“生产环境Agent可观测性是在用户感受到问题之前检测到性能退化”设置** proactive alerts**P99延迟 阈值、Turn预算命中率 阈值、Token消耗突增。④ Trace是评估的基础“生产环境的trace成为持续改进的基础”不要只在出问题时才看trace。定期采样生产trace进行离线评估发现潜在问题。8.2 常见陷阱陷阱1只看最终答案不看执行轨迹Agent可能答对了但走了很“蠢”的路——调了不该调的工具、浪费了大量Token。只看最终答案会掩盖这些问题。陷阱2成本追踪不完整LangSmith默认只对OpenAI和Anthropic自动计算成本。如果使用DeepSeek、通义等国产模型需要手动配置模型定价。陷阱3Trace太长无法人工翻阅长期运行的Agent可能产生成百上千个观察节点的trace。需要善用搜索、过滤和聚合视图而不是试图手工翻阅完整trace树。陷阱4没有设置Turn预算“没有Turn预算的Agent就像没有停机按钮的跑步机”设置合理的迭代次数上限如25次超过则触发人工介入。九、实战小练习作业练习为你的Agent配置完整可观测性需求注册LangSmith账号并获取API Key可选部署自托管LangFuse或使用云版本为你之前开发的Agent配置双重追踪LangSmith LangFuse添加至少一个observe()装饰的自定义函数模拟运行5个不同场景在LangSmith/LangFuse中查看trace设置一个成本告警单会话成本 $0.5提示代码框架# 1. 配置环境变量os.environ[LANGSMITH_TRACING]trueos.environ[LANGSMITH_API_KEY]xxx# 2. 初始化LangFusefromlangfuse.callbackimportCallbackHandler langfuse_handlerCallbackHandler(public_keyxxx,secret_keyxxx)# 3. 创建Agent复用之前的代码agentcreate_agent(...)# 4. 执行并追踪resultagent.invoke({messages:[...]},{callbacks:[langfuse_handler]})# 5. 在LangSmith/LangFuse控制台查看trace结语今天这节课我们全面学习了Agent的可观测性与监控知识点核心内容为什么不同Agent调试的是“推理”不是“代码”三大支柱Logs发生了什么 Traces为什么发生 Metrics发生了多少LangSmithLangChain官方平台Agent自动支持追踪LangFuse开源替代方案支持自托管OpenTelemetry开放标准一次采集、多处发送核心指标延迟(P50/P90/P99)、吞吐、Token消耗、Turn预算、成本成本监控LangSmith自动记录手动上报自定义成本最佳实践分层采集、成本断路器、主动监控、trace驱动评估至此模块五工程篇的第21节已完成课时内容状态第19节Agent的评估与测试✅第20节Agent的部署与上线✅第21节Agent的可观测性与监控✅第22节Agent的性能优化待生成下节课第22节我们将学习Agent的性能优化——延迟优化、成本优化、质量优化让你的Agent又快又便宜又准如果觉得有帮助欢迎点赞、收藏、评论三连我们下节课见 本文是《AI Agent开发实战》课程第21节的完整内容系列文章持续更新中关注我不迷路 21 - Agent的可观测性与监控！从Logging到Tracing再到成本告警，一篇搞定生产级全链路可观测
适合前后端/测试等有编程基础的同学手把手教你让Agent在线上“裸奔”变“透明”前言通过前面20节课的学习你已经能把Agent打包成生产级服务、部署到Kubernetes、扛住并发请求了。它在线上跑得飞起用户开始用起来了。然后凌晨2点你被一通电话吵醒——“Agent好像疯了一直在调用工具已经跑了5分钟还没停……”你爬起来打开日志看到几百行乱七八糟的输出打开数据库发现某个表被查了几百次打开云厂商控制台看到API费用在疯狂飙升。你完全不知道Agent刚才做了什么、为什么这么做、该怎么修。这就是没有可观测性的后果。一句话定义Agent的可观测性是通过日志Logs、追踪Traces、指标Metrics三大支柱对Agent的每一次推理、每一个工具调用、每一轮决策进行结构化采集和分析让你能回答“Agent做了什么、为什么这么做、结果怎么样”的系统性能力。Agent的可观测性不是“锦上添花”而是生产环境的刚需。全文约8500字包含完整可运行的代码。一、为什么Agent的可观测性如此不同1.1 传统软件 vs AI Agent调试对象的根本变化在传统软件中调试是线性的、确定的代码出Bug → 看错误日志 → 找堆栈跟踪 → 定位出错的代码行 → 修复 → 上线但AI Agent完全不同当Agent用200步、耗时2分钟完成一个任务在中间某一步出错了——没有堆栈跟踪因为没有“代码”出错。出错的是Agent的推理。你要回答的是这样的问题为什么Agent在第23步选择了edit_file而不是read_file当时Agent看到了什么上下文和Prompt指令在这2分钟、200步的执行轨迹中Agent是从哪一步开始“跑偏”的传统追踪工具回答不了这些问题。1.2 Agent可观测性的三大独特挑战挑战说明后果故障隐藏在执行轨迹中Agent可能选错工具、检索错文档、陷入死循环但仍能输出一个“看似合理”的最终答案用户报告问题之前你可能完全不知道Agent自己决定花多少钱Agent自主决定调用多少次模型、执行多少个工具成本是动态的一个失控的Agent可能几分钟内烧掉你一个月的预算执行轨迹极长长期运行的Agent可能产生包含成百上千个观察节点的trace人类无法手工翻阅需要结构化的搜索和聚合能力1.3 可观测性三大支柱Logs Traces Metrics┌─────────────────────────────────────────────────────────────────┐ │ 可观测性三大支柱 │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Logs │ │ Traces │ │ Metrics │ │ │ │ 日志 │ │ 追踪 │ │ 指标 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ ↓ ↓ ↓ │ │ “发生了什么” “为什么发生” “发生了多少” │ │ 结构化事件记录 完整调用链路 聚合统计数据 │ │ 错误/警告/信息 每步的输入输出 延迟/吞吐/错误率 │ │ │ │ 三者结合 → 回答Agent做了什么、为什么这么做、效果怎么样 │ └─────────────────────────────────────────────────────────────────┘二、核心工具一LangSmith —— LangChain官方可观测平台2.1 什么是LangSmithLangSmith是LangChain团队构建的LLM应用可观测性平台专为捕获、调试、评估和监控LLM应用行为而设计。使用LangSmith的Agent自动支持追踪——所有用create_agent构建的Agent无需额外代码即可获得完整的可观测能力。2.2 快速启用LangSmith追踪只需设置三个环境变量exportLANGSMITH_TRACINGtrueexportLANGSMITH_API_KEYyour-langsmith-api-keyexportLANGSMITH_PROJECTmy-production-agent# 可选指定项目名然后正常运行你的Agent代码所有步骤都会被自动记录到LangSmith。2.3 LangSmith能追踪什么数据类型说明完整trace树从用户输入到最终输出的每一步工具调用Agent选择了哪个工具、传入了什么参数、返回了什么结果LLM调用每次调用的prompt、completion、model参数、token用量决策点Agent在每个步骤的推理和选择成本自动记录token消耗和费用中间步骤Agent的完整思考轨迹2.4 LangSmith Engine自动故障诊断LangSmith不只是“看板”它还能主动帮你修BugLangSmith Engine会监视你的生产trace将故障聚类为命名问题诊断根因并自动提交包含修复方案的PR。这意味着从“发现问题 → 定位原因 → 修复上线”的闭环可以被大幅缩短。2.5 选择性追踪与精细化控制不是所有调用都需要追踪。你可以用tracing_context精确控制哪些部分被追踪fromlangchain_core.tracersimportLangChainTracer# 只追踪特定调用tracerLangChainTracer()# 这个调用会被追踪awaitagent.invoke({messages:[{role:user,content:重要请求}]},{callbacks:[tracer]})# 这个调用不会被追踪如果LANGSMITH_TRACING未设置awaitagent.invoke({messages:[{role:user,content:普通请求}]})三、核心工具二LangFuse —— 开源LLM可观测平台3.1 什么是LangFuseLangFuse是一个开源的LLM工程平台提供追踪、评估、Prompt管理和数据集实验等能力。与LangSmith的核心区别维度LangSmithLangFuse开源❌ 闭源SaaS✅ 开源可自托管数据主权数据在LangChain云端数据在你自己的基础设施中定价按量付费开源版免费企业版付费Agent支持✅ 原生深度集成✅ 通过CallbackHandler集成3.2 快速集成LangFuse安装pipinstalllangfuse集成到LangChain/LangGraphfromlangfuse.callbackimportCallbackHandlerfromlangchain.agentsimportcreate_agentfromlangchain_openaiimportChatOpenAI# 1. 初始化LangFuse Handlerlangfuse_handlerCallbackHandler(public_keypk-lf-xxx,secret_keysk-lf-xxx,hosthttps://cloud.langfuse.com# 或自托管地址)# 2. 创建AgentllmChatOpenAI(modeldeepseek-v4-flash)agentcreate_agent(modelllm,tools[...])# 3. 带追踪执行resultagent.invoke({messages:[{role:user,content:...}]},{callbacks:[langfuse_handler]})3.3 LangFuse的Agent专用功能LangFuse在2025年11月加入了Agent Graphs功能能从观测的时间与嵌套中推断图结构直观展示多步Agent的执行流程。支持的10种观测类型类型说明event通用事件span时间段generationLLM生成agentAgent步骤tool工具调用chainChain执行retriever检索步骤evaluator评估embedding向量化guardrail安全护栏3.4 observe()装饰器追踪自定义逻辑对于LangChain之外的自定义逻辑如数据清洗、API格式化可以用observe()装饰器自动追踪fromlangfuse.decoratorsimportobserveobserve()defpreprocess_user_input(raw_text:str)-str:# 自定义预处理逻辑returncleaned_textobserve()defformat_agent_output(raw_output:str)-dict:# 自定义格式化逻辑return{result:raw_output,format:json}四、开放标准OpenTelemetryOTel4.1 为什么需要OpenTelemetryLangSmith和LangFuse都是优秀的工具但它们各自有各自的SDK和API。如果有一天你想从LangSmith切换到LangFuse或者同时使用多个后端怎么办OpenTelemetryOTel就是答案——它是一个开放标准让你用一套API采集遥测数据然后发送到任意支持OTel的后端。4.2 OTel SigNoz开源可观测性栈SigNoz是一个开源的APM应用性能监控工具原生支持OpenTelemetry。安装依赖pipinstallopentelemetry-distro\opentelemetry-exporter-otlp\openinference-instrumentation-langchain\langchain langgraph自动instrumentationopentelemetry-bootstrap--actioninstall配置并运行fromlangchain.agentsimportcreate_agent agentcreate_agent(modeldeepseek-v4-flash,tools[...])# 所有调用会自动通过OTel采集并发送到SigNozresultagent.invoke({messages:[{role:user,content:...}]})4.3 OTel Grafana Cloud企业级可观测性Grafana Cloud也提供了针对AI Agent的预构建仪表板可分析响应时间、错误率、吞吐量和Token用量。4.4 阿里云LoongSuiteOTel GenAI语义规范阿里云基于OTel社区标准推出了LoongSuite GenAI可观测语义规范并提供了无侵入采集方案让Agent实现“可看见、可分析、可审计、可治理”。五、监控什么—— Agent核心指标体系5.1 性能指标Performance Metrics这些指标告诉你Agent跑得有多快、有多稳指标说明告警建议延迟P50/P90/P99追踪所有三个百分位P99揭示平均延迟隐藏的“长尾”问题P99 30s 告警吞吐量Throughput按会话级别测量每秒请求数而非仅按LLM调用突降50%告警每会话Token消耗高Token数意味着失控的推理循环或低效的Prompt构造单会话 100k tokens 告警迭代次数每个会话的循环迭代次数 25次触发人工介入工具调用频率/失败率Agent调用工具的次数和失败比例失败率 10%告警5.2 质量指标Quality Metrics这些指标告诉你Agent回答得好不好指标说明评估方式幻觉频率Agent输出中包含未被检索上下文支持的主张的频率LLM-as-Judge接地性与相关性检索到的chunk是否真正支持最终答案人工/LLM评估检索精确率Agent在“噪声上下文”中工作的比例规则/LLM评估5.3 成本与安全指标Cost Safety Metrics这些指标是大多数团队最容易忽视的但恰恰是最重要的指标说明告警建议Turn预算限制每个会话的迭代次数防止失控和无限循环达到80%预算告警成本断路器设置会话级成本上限在单个失控会话耗尽预算前停止执行超过预算阈值自动熔断Token用量按项目、按用户、按模型维度聚合日环比增长 50%告警六、成本监控让每一分钱都花得明明白白6.1 LangSmith成本追踪LangSmith自动记录主流LLM提供商的token用量和成本并提供统一视图。在LangSmith UI中查看成本的三种方式方式说明Trace树内每个运行节点的详细token和成本明细项目统计项目内所有trace的汇总token和成本仪表板成本和token用量随时间变化的趋势成本归因维度# LangSmith支持按运行类型归类成本# 你可以查询LLM调用花了多少钱、Retriever花了多少钱、Tool调用花了多少钱# 这让你清楚地知道管道中哪个组件消耗了最多的token和成本6.2 LangFuse成本告警LangFuse提供可配置阈值的支出告警当成本超过设定阈值时自动通知。6.3 手动上报自定义成本对于非LLM组件如外部API调用、向量数据库查询可以手动上报成本fromlangsmithimporttraceabletraceable(run_typetool)defcall_external_api(query:str):# 执行外部调用resultrequests.post(https://api.example.com/search,json{q:query})# 手动上报成本# 在当前run上附加成本数据returnresult.json()七、实战为生产Agent配置完整可观测性7.1 三层可观测性架构┌─────────────────────────────────────────────────────────────────┐ │ 三层可观测性架构 │ │ │ │ 第一层Agent框架层自动 │ │ ├── LangSmith Tracing所有Agent自动支持 │ │ └── 自动记录工具调用、LLM调用、决策点、token用量 │ │ │ │ 第二层自定义业务层手动 │ │ ├── observe() / traceable 装饰自定义逻辑 │ │ └── 记录业务指标、用户反馈、领域特定事件 │ │ │ │ 第三层基础设施层OTel │ │ ├── OpenTelemetry采集系统级指标 │ │ └── 记录CPU、内存、网络、数据库连接池 │ └─────────────────────────────────────────────────────────────────┘7.2 完整代码示例importosfromlangchain.agentsimportcreate_agentfromlangchain.toolsimporttoolfromlangchain_openaiimportChatOpenAIfromlangfuse.callbackimportCallbackHandlerfromlangfuse.decoratorsimportobserve# 1. 配置LangSmith os.environ[LANGSMITH_TRACING]trueos.environ[LANGSMITH_API_KEY]your-langsmith-keyos.environ[LANGSMITH_PROJECT]production-agent# 2. 配置LangFuse langfuse_handlerCallbackHandler(public_keypk-lf-xxx,secret_keysk-lf-xxx,hosthttps://cloud.langfuse.com)# 3. 定义工具带自定义追踪 toolobserve()# LangFuse自动追踪defget_weather(city:str)-str:获取城市天气returnf{city}晴25°Ctoolobserve()defsearch_database(query:str)-str:搜索内部知识库# 模拟数据库查询returnf找到关于{query}的3条记录# 4. 自定义业务逻辑追踪 observe()defpreprocess_query(raw:str)-str:预处理用户输入returnraw.strip().lower()observe()defpostprocess_response(raw:str)-dict:后处理Agent输出return{content:raw,length:len(raw),timestamp:2026-08-20T10:00:00Z}# 5. 创建Agent llmChatOpenAI(modeldeepseek-v4-flash,temperature0.3)agentcreate_agent(modelllm,tools[get_weather,search_database],system_prompt你是一个智能助手可以查询天气和搜索知识库)# 6. 执行带多层可观测性 defrun_agent_with_observability(user_query:str):# 预处理被observe追踪processedpreprocess_query(user_query)# Agent执行LangSmith自动追踪 LangFuse手动追踪resultagent.invoke({messages:[{role:user,content:processed}]},{callbacks:[langfuse_handler]}# LangFuse追踪)# 后处理被observe追踪finalpostprocess_response(result[messages][-1].content)returnfinal# 测试responserun_agent_with_observability(北京天气怎么样)print(response)7.3 可观测性检查清单检查项工具状态✅ Agent每一步的traceLangSmith / LangFuse自动✅ 工具调用记录LangSmith / LangFuse自动✅ Token用量和成本LangSmith / LangFuse自动✅ 自定义业务逻辑observe / traceable手动添加✅ 延迟百分位P50/P90/P99Prometheus Grafana需配置✅ 错误率和告警Prometheus AlertManager需配置✅ 会话级成本断路器自定义中间件需实现✅ 用户反馈采集LangSmith / LangFuse需配置八、最佳实践与常见陷阱8.1 生产环境可观测性最佳实践① 分层采集各司其职层级采集内容工具Agent框架层trace、工具调用、LLM调用LangSmith/LangFuse业务逻辑层自定义事件、用户反馈observe装饰器基础设施层CPU、内存、网络OpenTelemetry Prometheus② 设置成本断路器# 在Agent执行前检查成本MAX_COST_PER_SESSION1.0# 美元defcheck_cost_budget(current_cost:float):ifcurrent_costMAX_COST_PER_SESSION:raiseException(f成本超限${current_cost} ${MAX_COST_PER_SESSION})③ 主动监控而非被动响应“生产环境Agent可观测性是在用户感受到问题之前检测到性能退化”设置** proactive alerts**P99延迟 阈值、Turn预算命中率 阈值、Token消耗突增。④ Trace是评估的基础“生产环境的trace成为持续改进的基础”不要只在出问题时才看trace。定期采样生产trace进行离线评估发现潜在问题。8.2 常见陷阱陷阱1只看最终答案不看执行轨迹Agent可能答对了但走了很“蠢”的路——调了不该调的工具、浪费了大量Token。只看最终答案会掩盖这些问题。陷阱2成本追踪不完整LangSmith默认只对OpenAI和Anthropic自动计算成本。如果使用DeepSeek、通义等国产模型需要手动配置模型定价。陷阱3Trace太长无法人工翻阅长期运行的Agent可能产生成百上千个观察节点的trace。需要善用搜索、过滤和聚合视图而不是试图手工翻阅完整trace树。陷阱4没有设置Turn预算“没有Turn预算的Agent就像没有停机按钮的跑步机”设置合理的迭代次数上限如25次超过则触发人工介入。九、实战小练习作业练习为你的Agent配置完整可观测性需求注册LangSmith账号并获取API Key可选部署自托管LangFuse或使用云版本为你之前开发的Agent配置双重追踪LangSmith LangFuse添加至少一个observe()装饰的自定义函数模拟运行5个不同场景在LangSmith/LangFuse中查看trace设置一个成本告警单会话成本 $0.5提示代码框架# 1. 配置环境变量os.environ[LANGSMITH_TRACING]trueos.environ[LANGSMITH_API_KEY]xxx# 2. 初始化LangFusefromlangfuse.callbackimportCallbackHandler langfuse_handlerCallbackHandler(public_keyxxx,secret_keyxxx)# 3. 创建Agent复用之前的代码agentcreate_agent(...)# 4. 执行并追踪resultagent.invoke({messages:[...]},{callbacks:[langfuse_handler]})# 5. 在LangSmith/LangFuse控制台查看trace结语今天这节课我们全面学习了Agent的可观测性与监控知识点核心内容为什么不同Agent调试的是“推理”不是“代码”三大支柱Logs发生了什么 Traces为什么发生 Metrics发生了多少LangSmithLangChain官方平台Agent自动支持追踪LangFuse开源替代方案支持自托管OpenTelemetry开放标准一次采集、多处发送核心指标延迟(P50/P90/P99)、吞吐、Token消耗、Turn预算、成本成本监控LangSmith自动记录手动上报自定义成本最佳实践分层采集、成本断路器、主动监控、trace驱动评估至此模块五工程篇的第21节已完成课时内容状态第19节Agent的评估与测试✅第20节Agent的部署与上线✅第21节Agent的可观测性与监控✅第22节Agent的性能优化待生成下节课第22节我们将学习Agent的性能优化——延迟优化、成本优化、质量优化让你的Agent又快又便宜又准如果觉得有帮助欢迎点赞、收藏、评论三连我们下节课见 本文是《AI Agent开发实战》课程第21节的完整内容系列文章持续更新中关注我不迷路