Agent开发最痛苦的部分是调试。传统代码调试你能看到每一行执行的结果。Agent调试你只能看到输入 → 输出中间的推理过程是个黑盒。这篇文章我们讨论Agent调试的方法和工具怎么追踪Agent的推理过程怎么分析问题怎么快速定位原因。为什么Agent调试难问题1推理过程不可见# 代码调试清晰可见defprocess(data):step1transform(data)# 能看到step1step2validate(step1)# 能看到step2returnexecute(step2)# Agent调试黑盒responseagent.run(user_input)# 中间发生了什么不知道问题2结果不确定# 同一输入可能不同输出agent.run(退款订单123)# 第一次调用refund工具agent.run(退款订单123)# 第二次先查询再退款agent.run(退款订单123)# 第三次直接返回文字好的问题3错误信息模糊# Agent报错AgentExecutionError:Agent failed to complete task# 这个错误说明什么# - Prompt问题# - 工具问题# - LLM问题# - 状态问题调试的基础日志追踪调试的第一步是让推理过程可见。手动日志最简单的方式在每个关键点打印日志。# logging_agent.pyimportlogging logging.basicConfig(levellogging.INFO)loggerlogging.getLogger(__name__)classDebuggableAgent:可调试的Agentdefrun(self,user_input:str)-str:trace_idself._generate_trace_id()logger.info(f[{trace_id}] 开始处理:{user_input})# 步骤1意图识别intentself._detect_intent(user_input)logger.info(f[{trace_id}] 意图识别结果:{intent})# 步骤2工具选择toolsself._select_tools(intent)logger.info(f[{trace_id}] 选择工具:{tools})# 步骤3工具执行fortool_nameintools:logger.info(f[{trace_id}] 调用工具:{tool_name})resultself._call_tool(tool_name,user_input)logger.info(f[{trace_id}] 工具返回:{result})# 步骤4生成响应responseself._generate_response()logger.info(f[{trace_id}] 最终响应:{response})returnresponse结构化追踪更好的方式结构化记录每一步。# trace.pyfromdataclassesimportdataclass,fieldfromtypingimportList,AnyfromdatetimeimportdatetimeimportjsondataclassclassTraceStep:追踪步骤step_name:strinput_data:Any output_data:Any timestamp:datetime duration_ms:floatmetadata:dictfield(default_factorydict)dataclassclassAgentTrace:Agent执行追踪trace_id:struser_input:strsteps:List[TraceStep]field(default_factorylist)final_output:strtotal_duration_ms:float0defadd_step(self,step:TraceStep):self.steps.append(step)defto_dict(self)-dict:return{trace_id:self.trace_id,user_input:self.user_input,steps:[{step_name:s.step_name,input:s.input_data,output:s.output_data,timestamp:s.timestamp.isoformat(),duration_ms:s.duration_ms}forsinself.steps],final_output:self.final_output,total_duration_ms:self.total_duration_ms}classTracingAgent:带追踪的Agentdef__init__(self):self.traces:List[AgentTrace][]defrun(self,user_input:str)-str:importtime start_timetime.time()trace_idself._generate_trace_id()traceAgentTrace(trace_idtrace_id,user_inputuser_input)try:# 意图识别step_starttime.time()intentself._detect_intent(user_input)trace.add_step(TraceStep(step_namedetect_intent,input_datauser_input,output_dataintent,timestampdatetime.now(),duration_ms(time.time()-step_start)*1000))# 工具调用fortool_nameinself._get_tools(intent):step_starttime.time()resultself._call_tool(tool_name,user_input)trace.add_step(TraceStep(step_nameftool_{tool_name},input_datauser_input,output_dataresult,timestampdatetime.now(),duration_ms(time.time()-step_start)*1000))# 生成响应step_starttime.time()responseself._generate_response()trace.add_step(TraceStep(step_namegenerate_response,input_dataNone,output_dataresponse,timestampdatetime.now(),duration_ms(time.time()-step_start)*1000))trace.final_outputresponseexceptExceptionase:trace.add_step(TraceStep(step_nameerror,input_dataNone,output_datastr(e),timestampdatetime.now(),duration_ms0,metadata{error:True}))trace.total_duration_ms(time.time()-start_time)*1000self.traces.append(trace)returntrace.final_outputdefget_last_trace(self)-AgentTrace:returnself.traces[-1]ifself.traceselseNoneLangSmith专业调试工具LangSmith是LangChain官方的调试和监控工具。基本使用# langsmith_setup.pyimportos# 设置环境变量os.environ[LANGCHAIN_TRACING_V2]trueos.environ[LANGCHAIN_API_KEY]your-api-keyos.environ[LANGCHAIN_PROJECT]customer-service-agent# 之后所有LangChain调用都会自动追踪fromlangchain.agentsimportcreate_react_agent agentcreate_react_agent(llm,tools,prompt)resultagent.invoke({input:退款订单123})# 打开 https://smith.langchain.com 查看追踪追踪内容LangSmith自动记录输入输出每个节点的输入和输出LLM调用Prompt、温度、token数、响应工具调用工具名、参数、返回值、耗时时间线每个步骤的开始和结束时间分析问题在LangSmith界面用户输入: 退款订单123 │ ├─ LLM调用 (234 tokens, 1.2s) │ Prompt: 你是客服Agent... │ Output: Thought: 用户想退款我需要... │ ├─ 工具调用: query_order (0.3s) │ Input: {order_id: 123} │ Output: 订单存在状态已签收 │ ├─ LLM调用 (189 tokens, 0.8s) │ Output: Thought: 订单可退款执行退款 │ ├─ 工具调用: refund (0.5s) │ Input: {order_id: 123} │ Output: 退款成功 │ └─ 最终输出: 您的订单123已退款...常见调试场景场景1Agent没有调用工具现象Agent直接返回文字没有调用工具。追踪LLM输出: 好的我来帮您处理退款。 没有工具调用原因Prompt没说明要调用工具工具描述不够清晰LLM认为不需要工具修复# 在Prompt中强调工具使用prompt 你是退款Agent。处理退款时必须调用refund工具。 不要直接用文字回复必须调用工具执行。 场景2Agent调用错误工具现象应该调用refund却调用了query。追踪LLM推理: 用户要退款我先查一下订单信息 工具调用: query_order (期望是refund)原因工具描述有歧义Agent推理逻辑问题修复# 明确工具使用条件tooldefrefund(order_id:str)-str: 执行退款操作。当用户明确要求退款时调用此工具。 不要用于查询订单状态。 场景3Agent无限循环现象Agent一直调用同一个工具不停止。追踪工具调用: query_order 工具返回: 订单123状态已签收 LLM推理: 我再确认一下订单状态 工具调用: query_order (第2次) 工具返回: 订单123状态已签收 LLM推理: 我还需要确认一下 工具调用: query_order (第3次) ...原因没有明确的终止条件Prompt没有限制重复调用修复# 添加循环限制classAgent:max_iterations5defrun(self,user_input:str)-str:foriinrange(self.max_iterations):# ...return处理超时请联系人工调试工具清单工具用途适用场景LangSmith完整追踪LangChain项目手动日志简单追踪快速调试结构化Trace自定义追踪非LangChain项目LLM调试模式查看推理过程分析LLM决策总结Agent调试的关键让推理过程可见追踪每一步结构化记录便于分析使用专业工具LangSmith常见模式识别快速定位问题调试Agent比调试代码难但有了追踪和分析方法可以大幅提升效率。下一篇我们讨论Agent测试策略。