Agent可观测性如何监控、调试、追踪你的智能体附完整方案 导读Agent上线了但你不知道它在想什么、做了什么、为什么出错可观测性Observability是Agent从Demo走向生产的必备基础设施今天给你一套完整的监控、调试、追踪方案一、Agent可观测性为什么难1.1 传统应用 vs Agent应用维度传统应用Agent应用执行路径确定性代码写死的非确定性LLM决策延迟可预测波动大几秒到几分钟成本主要是计算资源Token消耗按次计费错误类型异常/超时幻觉/死循环/工具调用失败调试难度看日志就行需要看思考过程核心挑战Agent的每一步决策都是LLM想出来的你需要看到它的思考链而不只是输入输出。1.2 可观测性三大支柱 Agent可观测性 日志 Logging 指标 Metrics 追踪 Tracing每步决策日志工具调用记录错误堆栈响应延迟Token消耗成功率完整执行链路每步耗时输入输出快照二、LangSmithAgent的X光机 2.1 什么是LangSmithLangSmith LangChain官方的可观测性平台专门用于追踪、调试、评估Agent。功能说明Trace追踪可视化Agent的每一步执行指标监控延迟、Token、成功率等评估测试自动化评估Agent质量调试工具回放任意一次执行数据分析趋势分析、异常检测2.2 接入LangSmithimportos# 配置LangSmithos.environ[LANGCHAIN_TRACING_V2]trueos.environ[LANGCHAIN_API_KEY]your-api-keyos.environ[LANGCHAIN_PROJECT]my-agent-project# 之后的所有LangChain调用都会自动追踪fromlangchain_openaiimportChatOpenAIfromlangchain.agentsimportcreate_agent llmChatOpenAI(modelgpt-4o)agentcreate_agent(modelllm,tools[...])# 运行Agent - 自动记录到LangSmithresultagent.invoke({messages:[...]})2.3 LangSmith追踪界面 Trace LLM Call耗时: 2.3sToken: 1500 Tool Callsearch_web耗时: 1.1s LLM Call耗时: 1.8sToken: 800 Tool Callread_file耗时: 0.3s LLM Call耗时: 1.2sToken: 600三、自定义日志系统 3.1 Agent日志框架importloggingimportjsonimporttimefromfunctoolsimportwraps# 配置日志loggerlogging.getLogger(agent)handlerlogging.FileHandler(/tmp/agent.log)handler.setFormatter(logging.Formatter({time:%(asctime)s,level:%(levelname)s,msg:%(message)s}))logger.addHandler(handler)logger.setLevel(logging.INFO)classAgentLogger:Agent专用日志记录器staticmethoddeflog_llm_call(model,prompt_tokens,completion_tokens,latency_ms):logger.info(json.dumps({event:llm_call,model:model,prompt_tokens:prompt_tokens,completion_tokens:completion_tokens,total_tokens:prompt_tokenscompletion_tokens,latency_ms:latency_ms}))staticmethoddeflog_tool_call(tool_name,input_data,output_data,latency_ms,successTrue):logger.info(json.dumps({event:tool_call,tool:tool_name,input:str(input_data)[:200],output:str(output_data)[:200],latency_ms:latency_ms,success:success}))staticmethoddeflog_agent_step(step_num,thought,action,observation):logger.info(json.dumps({event:agent_step,step:step_num,thought:thought[:200],action:action,observation:str(observation)[:200]}))staticmethoddeflog_error(error_type,error_msg,contextNone):logger.error(json.dumps({event:error,type:error_type,message:error_msg,context:str(context)[:500]ifcontextelseNone}))3.2 中间件集成fromlangchain.agents.middlewareimportwrap_tool_callfromlangchain.messagesimportToolMessagewrap_tool_calldeflogging_middleware(request,handler):记录每次工具调用的中间件tool_namerequest.tool_call[name]tool_inputrequest.tool_call[args]starttime.time()try:resulthandler(request)latencyint((time.time()-start)*1000)AgentLogger.log_tool_call(tool_name,tool_input,result.content,latency)returnresultexceptExceptionase:latencyint((time.time()-start)*1000)AgentLogger.log_tool_call(tool_name,tool_input,str(e),latency,successFalse)returnToolMessage(contentfError:{e},tool_call_idrequest.tool_call[id])四、关键监控指标 4.1 指标体系类别指标说明告警阈值⚡性能响应延迟P5050%请求的延迟 5s⚡性能响应延迟P9999%请求的延迟 30s成本单次Token消耗每次请求的Token 10000成本日均成本每日API费用 预算✅质量任务成功率成功完成的比例 90%✅质量工具调用成功率工具调用成功比例 95%循环平均步数Agent完成任务的步数 10步循环死循环检测连续重复动作 3次重复4.2 监控面板 Agent监控面板⚡ 延迟P50: 3.2sP99: 12.5s Token今日: 2.3M成本: ¥156✅ 成功率98.5%↑0.3% 步数平均: 4.2步最大: 12步五、调试技巧 5.1 常见问题排查表问题可能原因排查方法死循环Agent反复调用同一工具查看Trace检查重复动作幻觉LLM编造信息对比工具返回和Agent输出⏰超时工具调用太慢/步数太多检查各步骤耗时成本过高Token消耗过多分析Prompt长度和步数❌工具失败参数错误或权限不足查看工具调用日志答非所问System Prompt不够清晰检查Prompt和输入5.2 回放调试# 保存每次执行的完整记录defsave_execution_trace(thread_id,state):保存执行轨迹用于回放调试trace{thread_id:thread_id,timestamp:time.time(),messages:[{role:msg.typeifhasattr(msg,type)elsemsg[role],content:msg.contentifhasattr(msg,content)elsemsg[content]}formsginstate[messages]],total_steps:len([mforminstate[messages]ifhasattr(m,type)andm.typetool]),}# 保存到文件/数据库withopen(f/tmp/traces/{thread_id}.json,w)asf:json.dump(trace,f,ensure_asciiFalse,indent2)六、可观测性工具对比 工具类型优点缺点推荐场景LangSmith商业平台功能全面开箱即用收费LangChain项目Phoenix开源免费自托管需要自己部署预算有限OpenTelemetry标准协议通用生态好需要额外适配多框架混合自建日志自定义完全可控开发成本高特殊需求七、本期小结 知识点核心内容可观测性三支柱日志、指标、追踪LangSmithAgent专属的可观测性平台关键指标延迟、Token、成功率、步数调试技巧回放Trace、死循环检测工具选择LangSmith/Phoenix/OTel/自建没有可观测性的Agent 黑箱你永远不知道它在想什么、为什么出错。把可观测性作为Agent上线的第一优先级而不是事后补救 下期预告《Agent安全攻防Prompt注入、工具滥用、数据泄露三大风险与防御策略》—— Agent的安全问题比你想的更严重️三连走起可观测性让Agent不再是黑箱专栏第21/24期生产落地篇进行中…作者高炉炼铁智能化技术研究者专注钢铁冶金与人工智能 交叉领域。 如果觉得有帮助请点赞、收藏、转发版权归作者所有未经许可请勿抄袭套用商用(或其它具有利益性行为)。 关注专栏不错过后续精彩内容
AI Agent 从入门到封神：24 讲打造你的超级智能体~系列文章21：Agent可观测性：如何监控、调试、追踪你的智能体？
Agent可观测性如何监控、调试、追踪你的智能体附完整方案 导读Agent上线了但你不知道它在想什么、做了什么、为什么出错可观测性Observability是Agent从Demo走向生产的必备基础设施今天给你一套完整的监控、调试、追踪方案一、Agent可观测性为什么难1.1 传统应用 vs Agent应用维度传统应用Agent应用执行路径确定性代码写死的非确定性LLM决策延迟可预测波动大几秒到几分钟成本主要是计算资源Token消耗按次计费错误类型异常/超时幻觉/死循环/工具调用失败调试难度看日志就行需要看思考过程核心挑战Agent的每一步决策都是LLM想出来的你需要看到它的思考链而不只是输入输出。1.2 可观测性三大支柱 Agent可观测性 日志 Logging 指标 Metrics 追踪 Tracing每步决策日志工具调用记录错误堆栈响应延迟Token消耗成功率完整执行链路每步耗时输入输出快照二、LangSmithAgent的X光机 2.1 什么是LangSmithLangSmith LangChain官方的可观测性平台专门用于追踪、调试、评估Agent。功能说明Trace追踪可视化Agent的每一步执行指标监控延迟、Token、成功率等评估测试自动化评估Agent质量调试工具回放任意一次执行数据分析趋势分析、异常检测2.2 接入LangSmithimportos# 配置LangSmithos.environ[LANGCHAIN_TRACING_V2]trueos.environ[LANGCHAIN_API_KEY]your-api-keyos.environ[LANGCHAIN_PROJECT]my-agent-project# 之后的所有LangChain调用都会自动追踪fromlangchain_openaiimportChatOpenAIfromlangchain.agentsimportcreate_agent llmChatOpenAI(modelgpt-4o)agentcreate_agent(modelllm,tools[...])# 运行Agent - 自动记录到LangSmithresultagent.invoke({messages:[...]})2.3 LangSmith追踪界面 Trace LLM Call耗时: 2.3sToken: 1500 Tool Callsearch_web耗时: 1.1s LLM Call耗时: 1.8sToken: 800 Tool Callread_file耗时: 0.3s LLM Call耗时: 1.2sToken: 600三、自定义日志系统 3.1 Agent日志框架importloggingimportjsonimporttimefromfunctoolsimportwraps# 配置日志loggerlogging.getLogger(agent)handlerlogging.FileHandler(/tmp/agent.log)handler.setFormatter(logging.Formatter({time:%(asctime)s,level:%(levelname)s,msg:%(message)s}))logger.addHandler(handler)logger.setLevel(logging.INFO)classAgentLogger:Agent专用日志记录器staticmethoddeflog_llm_call(model,prompt_tokens,completion_tokens,latency_ms):logger.info(json.dumps({event:llm_call,model:model,prompt_tokens:prompt_tokens,completion_tokens:completion_tokens,total_tokens:prompt_tokenscompletion_tokens,latency_ms:latency_ms}))staticmethoddeflog_tool_call(tool_name,input_data,output_data,latency_ms,successTrue):logger.info(json.dumps({event:tool_call,tool:tool_name,input:str(input_data)[:200],output:str(output_data)[:200],latency_ms:latency_ms,success:success}))staticmethoddeflog_agent_step(step_num,thought,action,observation):logger.info(json.dumps({event:agent_step,step:step_num,thought:thought[:200],action:action,observation:str(observation)[:200]}))staticmethoddeflog_error(error_type,error_msg,contextNone):logger.error(json.dumps({event:error,type:error_type,message:error_msg,context:str(context)[:500]ifcontextelseNone}))3.2 中间件集成fromlangchain.agents.middlewareimportwrap_tool_callfromlangchain.messagesimportToolMessagewrap_tool_calldeflogging_middleware(request,handler):记录每次工具调用的中间件tool_namerequest.tool_call[name]tool_inputrequest.tool_call[args]starttime.time()try:resulthandler(request)latencyint((time.time()-start)*1000)AgentLogger.log_tool_call(tool_name,tool_input,result.content,latency)returnresultexceptExceptionase:latencyint((time.time()-start)*1000)AgentLogger.log_tool_call(tool_name,tool_input,str(e),latency,successFalse)returnToolMessage(contentfError:{e},tool_call_idrequest.tool_call[id])四、关键监控指标 4.1 指标体系类别指标说明告警阈值⚡性能响应延迟P5050%请求的延迟 5s⚡性能响应延迟P9999%请求的延迟 30s成本单次Token消耗每次请求的Token 10000成本日均成本每日API费用 预算✅质量任务成功率成功完成的比例 90%✅质量工具调用成功率工具调用成功比例 95%循环平均步数Agent完成任务的步数 10步循环死循环检测连续重复动作 3次重复4.2 监控面板 Agent监控面板⚡ 延迟P50: 3.2sP99: 12.5s Token今日: 2.3M成本: ¥156✅ 成功率98.5%↑0.3% 步数平均: 4.2步最大: 12步五、调试技巧 5.1 常见问题排查表问题可能原因排查方法死循环Agent反复调用同一工具查看Trace检查重复动作幻觉LLM编造信息对比工具返回和Agent输出⏰超时工具调用太慢/步数太多检查各步骤耗时成本过高Token消耗过多分析Prompt长度和步数❌工具失败参数错误或权限不足查看工具调用日志答非所问System Prompt不够清晰检查Prompt和输入5.2 回放调试# 保存每次执行的完整记录defsave_execution_trace(thread_id,state):保存执行轨迹用于回放调试trace{thread_id:thread_id,timestamp:time.time(),messages:[{role:msg.typeifhasattr(msg,type)elsemsg[role],content:msg.contentifhasattr(msg,content)elsemsg[content]}formsginstate[messages]],total_steps:len([mforminstate[messages]ifhasattr(m,type)andm.typetool]),}# 保存到文件/数据库withopen(f/tmp/traces/{thread_id}.json,w)asf:json.dump(trace,f,ensure_asciiFalse,indent2)六、可观测性工具对比 工具类型优点缺点推荐场景LangSmith商业平台功能全面开箱即用收费LangChain项目Phoenix开源免费自托管需要自己部署预算有限OpenTelemetry标准协议通用生态好需要额外适配多框架混合自建日志自定义完全可控开发成本高特殊需求七、本期小结 知识点核心内容可观测性三支柱日志、指标、追踪LangSmithAgent专属的可观测性平台关键指标延迟、Token、成功率、步数调试技巧回放Trace、死循环检测工具选择LangSmith/Phoenix/OTel/自建没有可观测性的Agent 黑箱你永远不知道它在想什么、为什么出错。把可观测性作为Agent上线的第一优先级而不是事后补救 下期预告《Agent安全攻防Prompt注入、工具滥用、数据泄露三大风险与防御策略》—— Agent的安全问题比你想的更严重️三连走起可观测性让Agent不再是黑箱专栏第21/24期生产落地篇进行中…作者高炉炼铁智能化技术研究者专注钢铁冶金与人工智能 交叉领域。 如果觉得有帮助请点赞、收藏、转发版权归作者所有未经许可请勿抄袭套用商用(或其它具有利益性行为)。 关注专栏不错过后续精彩内容
