AI Agent 从入门到封神：24 讲打造你的超级智能体~系列文章21：Agent可观测性：如何监控、调试、追踪你的智能体？

Agent可观测性：如何监控、调试、追踪你的智能体？（附完整方案） 🔍

导读：Agent上线了，但你不知道它在想什么、做了什么、为什么出错？可观测性（Observability）是Agent从Demo走向生产的必备基础设施！今天给你一套完整的监控、调试、追踪方案！📊

一、Agent可观测性为什么难？🤔

1.1 传统应用 vs Agent应用

💡核心挑战：Agent的每一步决策都是LLM"想"出来的，你需要看到它的思考链，而不只是输入输出。

1.2 可观测性三大支柱

二、LangSmith：Agent的"X光机" 🏥

2.1 什么是LangSmith？

LangSmith = LangChain官方的可观测性平台，专门用于追踪、调试、评估Agent。

2.2 接入LangSmith

importos# 配置LangSmithos.environ["LANGCHAIN_TRACING_V2"]="true"os.environ["LANGCHAIN_API_KEY"]="your-api-key"os.environ["LANGCHAIN_PROJECT"]="my-agent-project"# 之后的所有LangChain调用都会自动追踪fromlangchain_openaiimportChatOpenAIfromlangchain.agentsimportcreate_agent llm=ChatOpenAI(model="gpt-4o")agent=create_agent(model=llm,tools=[...])# 运行Agent - 自动记录到LangSmithresult=agent.invoke({"messages":[...]})

2.3 LangSmith追踪界面

三、自定义日志系统 📋

3.1 Agent日志框架

importloggingimportjsonimporttimefromfunctoolsimportwraps# 配置日志logger=logging.getLogger("agent")handler=logging.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_tokens+completion_tokens,"latency_ms":latency_ms}))@staticmethoddeflog_tool_call(tool_name,input_data,output_data,latency_ms,success=True):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,context=None):logger.error(json.dumps({"event":"error","type":error_type,"message":error_msg,"context":str(context)[:500]ifcontextelseNone}))

3.2 中间件集成

fromlangchain.agents.middlewareimportwrap_tool_callfromlangchain.messagesimportToolMessage@wrap_tool_calldeflogging_middleware(request,handler):"""记录每次工具调用的中间件"""tool_name=request.tool_call["name"]tool_input=request.tool_call["args"]start=time.time()try:result=handler(request)latency=int((time.time()-start)*1000)AgentLogger.log_tool_call(tool_name,tool_input,result.content,latency)returnresultexceptExceptionase:latency=int((time.time()-start)*1000)AgentLogger.log_tool_call(tool_name,tool_input,str(e),latency,success=False)returnToolMessage(content=f"Error:{e}",tool_call_id=request.tool_call["id"])

四、关键监控指标 📊

4.1 指标体系

4.2 监控面板

五、调试技巧 🐛

5.1 常见问题排查表

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.type=="tool"]),}# 保存到文件/数据库withopen(f"/tmp/traces/{thread_id}.json","w")asf:json.dump(trace,f,ensure_ascii=False,indent=2)

六、可观测性工具对比 📊

七、本期小结 📝

🔥没有可观测性的Agent = 黑箱！你永远不知道它在想什么、为什么出错。把可观测性作为Agent上线的第一优先级，而不是事后补救！

📢 下期预告：《Agent安全攻防：Prompt注入、工具滥用、数据泄露，三大风险与防御策略》—— Agent的安全问题，比你想的更严重！🛡️

📌三连走起！可观测性，让Agent不再是黑箱！💪

📚专栏第21/24期，生产落地篇进行中…

作者：高炉炼铁智能化技术研究者，专注钢铁冶金与人工智能 交叉领域。

👍 如果觉得有帮助，请点赞、收藏、转发！
版权归作者所有，未经许可请勿抄袭，套用，商用(或其它具有利益性行为)。
🔔 关注专栏，不错过后续精彩内容