可观测性（observability） 核心概念

它是什么

可观测性（observability）指通过日志、追踪与指标回答「系统内部到底发生了什么」的能力。业界通行的实现是 OpenTelemetry 的三支柱模型：logs（一行一条的事件记录）、traces（一次请求/一次运行的完整路径）、metrics（随时间聚合的数值），三者在生产系统里配合使用。对普通 Web 服务它是锦上添花，对 Agent 却是刚需：事件流（text_delta、tool_call_start、tool_result）推给前端就没了，中间轮次的 token 用量只存在于 done.usage，几十个会话的 print 日志混在一起分不清先后——smolagents 教程把这种情况概括为 agent runs are complicated to debug。

在本教程的实践

第 20 章给产品装上观测层，三件套对应三支柱的简化版：每个协议事件盖上全局序号 seq 与墙钟时间 ts，序列化成一行 JSON（structured-log）；一轮对话的事件序列聚合出一条 trace；token 用量按单价折算成成本（token-cost），失败事件归入 error / tool / budget 三桶看板。关键设计是观测层包在 onEvent 外面：loop 只负责 emit 协议事件，盖戳、聚合、记账、归桶全在 createTraceRecorder 与纯函数里，seq/ts 不进协议——把 server 和 cli 删掉，core 照常跑、照常测。

常见坑

• 观测逻辑塞进 core：在 loop 里直接 console.log、直接算成本——core 从此认识「可观测」，删掉观测模块 core 就变样；
• trace 过大：工具输出（读文件、搜索结果）可能很大，生产要截断 payload 或给 trace 设体积上限；
• 时间与顺序口径：ts 是观测层「看到」事件的时间、seq 才是排序键；多实例部署时全局 seq 要换成 (实例 id, 本地 seq)。

小结

一句话：日志回答「发生了什么」，trace 回答「这一次运行发生了什么、花了多少、成没成」。可观测性不是调试工具，而是 Agent 产品的运行数据底座——第 21 章用它回答「MCP 工具调用为什么失败、花了多少」。