Agent 系列（14）：Agent 可观测性——追踪每一步决策，让黑盒变透明

黑盒里的 Agent你启动了一个 Agent，发了一条请求，等了 6 秒，得到了回答。这 6 秒里发生了什么？LLM 思考了几次？工具调用了几次、传入了什么参数、返回了什么？延迟卡在哪一步？如果回答错了，是哪一步出了问题？普通agent.invoke()什么都不告诉你。Agent 的可观测性（Observability）就是解决这个问题：让你看到 Agent 每一步的决策和代价。三个可观测性层次开发阶段 → 实时 Trace （看到发生了什么） 分析阶段 → 延迟时间线 （看到时间花在哪里） 生产阶段 → 结构化审计日志 （记录每次请求，可回溯）三种模式使用同一套基础：LangChain 的BaseCallbackHandler。核心：AgentTracerLangChain 提供BaseCallbackHandler钩子，覆盖 LLM 调用和工具调用的生命周期：fromlangchain_core.callbacksimportBaseCallbackHandlerfromlangchain_core.outputsimportLLMResultclassAgentTracer(BaseCallbackHandler):def__init__(self,verbose:bool=True,trace_id:str="")-None:super().__init__()self.verbose=verbose self.trace_id=trace_idorstr(uuid.uuid4())[:8]self.steps:list[StepRecord]=[]self._llm_t0:float=0.0self._tool_t0:float=0.0self._tool_name:str=""# LLM 开始（Chat 模型走 on_chat_model_start，不是 on_llm_start）defon_chat_model_start(self,serialized,messages,**kwargs)-None:self._llm_t0=time.time()ifself.verbose:print(f" [LLM →] reasoning...")defon_llm_end(self,response:LLMResult,**kwargs)-None:t1=time.time()# 提取文本（工具调用轮次 content 为空，只有最终回答轮才有文字）output=_extract_text(response)self.steps.append(StepRecord(step_type="llm",name="LLM",output_preview=output,start_time