Agent 开发最让人抓狂的时刻往往不是模型答错了而是它答对了你却不知道为什么。链路一长工具调用、检索、重排、再生成中间任何一环出问题日志里只剩下一堆散落的 print。LangSmith 就是冲着这个痛点来的——它把 Agent 的每一步执行变成可回放、可对比、可打分的追踪记录。这篇内容适合已经在写 Agent、但还在用土办法调试的人也适合刚接触 Agent 开发、想一开始就把可观测性做对的人。我会从接入方式讲到链路拆解再到实际排查中的坑尽量把每个选择背后的理由说清楚。1. 为什么 Agent 调试不能只靠 print 和日志1.1 从一次真实的排查困境说起我最早做 Agent 的时候调试手段非常原始在每一步前后加 print把 prompt、工具返回、模型输出全打到控制台。单轮对话还能忍一旦 Agent 开始多步推理、连续调用三四个工具控制台就变成了一锅粥。你看到的是几十行交错的输出分不清哪段属于哪次调用更别说还原完整的执行顺序。问题的本质在于Agent 的执行是树状结构而不是线性的。一次用户请求进来可能触发一次规划规划里包含多个子任务每个子任务又可能调用工具、检索知识库、再触发一轮模型生成。这种嵌套关系用平铺的日志根本表达不出来。你需要的是一棵可以展开、折叠、逐层下钻的执行树而不是一条流水账。LangSmith 提供的正是这种树状视图。它把一次请求称为一个 tracetrace 下面挂着一层层的 run每个 run 对应一个具体操作——模型调用、工具执行、检索、链式处理。你可以点开任意一个 run看到它的输入、输出、耗时、token 消耗以及它下面还挂了哪些子 run。这个结构一旦建立起来排查效率是数量级的提升。1.2 可观测性三件套在 Agent 场景的落地传统后端讲可观测性说的是日志、指标、追踪三件套。放到 Agent 场景这三样东西的形态变了。日志对应的是每个 run 的详细输入输出指标对应的是 token 消耗、延迟、成功率、工具调用次数追踪对应的就是 trace 的树状结构。很多人只做了日志这一层把每次模型调用记下来就完事了。但 Agent 的问题往往出在关系上工具 A 的返回被错误地喂给了工具 B或者检索结果没被正确拼进 prompt。这类问题单看某一条日志是看不出来的必须把整条链路摆在一起对比。LangSmith 的价值就在于它天然把这三层整合在一个界面里你不需要自己搭一套 ELK 再写查询语句。还有一个容易被忽略的点Agent 的输出质量是概率性的。同一个 prompt 跑两次结果可能不同你没法像调试确定性代码那样复现 bug。这时候追踪记录就成了唯一的证据——你可以把出问题的那次 trace 存下来反复分析甚至拿它去做评测集的样本。这是纯日志做不到的。1.3 LangSmith 在 Agent 工具链里的位置需要说清楚的是LangSmith 不是 Agent 框架它不负责编排、不负责调用模型。它是一个观测和评测平台站在框架旁边看框架在干什么。你可以用 LangChain、LlamaIndex也可以自己手写编排逻辑只要在关键节点埋点上报它就能把链路画出来。这个定位决定了它的接入方式轻量、非侵入。你不需要为了用它而重构整个 Agent。它更像是在你的代码里插了一根探针探针负责把数据送到远端剩下的分析、对比、评测都在平台上完成。理解这一点很重要因为很多人一开始会误以为要学一套新框架其实不是。2. 接入 LangSmith 的几种姿势与选型逻辑2.1 环境变量接入最省事但也最容易踩坑最基础的接入方式是通过环境变量。设置好 API key 和项目名之后只要你的代码用的是 LangChain 生态的组件追踪会自动开启不需要改任何业务代码。这种方式适合快速验证几分钟就能看到第一条 trace。但这里有个坑环境变量是全局的一旦设置所有走 LangChain 的调用都会上报。如果你本地同时跑着好几个实验数据会混在同一个项目里看起来非常乱。我的做法是给每个实验单独指定项目名通过代码动态设置而不是写死在 shell 里。这样切换实验时不会互相污染。另一个坑是采样。默认情况下所有调用都上报量大了之后既费额度又拖慢响应。生产环境一定要配采样率比如只上报百分之十的请求或者只上报出错的请求。LangSmith 支持通过环境变量控制采样具体参数建议查官方文档因为不同版本字段名可能有差异。我的经验是本地开发全量上报预发环境按比例采样生产环境只上报异常和慢请求。2.2 手动埋点什么时候必须自己动手自动追踪覆盖的是框架内置的组件。一旦你的 Agent 里有自定义逻辑——比如自己写的路由函数、自己封装的重试机制、自己实现的缓存层——这些默认不会被追踪到。这时候就需要手动埋点。手动埋点用的是装饰器或者上下文管理器。装饰器适合包一个函数上下文管理器适合包一段代码块。两者的区别在于装饰器会自动把函数参数作为输入、返回值作为输出记录下来而上下文管理器需要你手动指定输入输出。选哪个取决于你的函数签名是否规整。我个人的习惯是对外暴露的工具函数用装饰器因为它们的输入输出天然就是结构化的中间的处理逻辑用上下文管理器因为那些中间变量往往不适合直接序列化。这个选择不是绝对的但能减少不少噪音。2.3 自建编排逻辑时的埋点策略如果你完全不用框架纯手写 Agent 循环那埋点就要自己规划。核心原则是把决策点和执行点分开埋。决策点是模型输出下一步动作的地方执行点是真正调用工具的地方。这两类 run 在追踪树里应该处于不同层级决策点在上执行点在下。这样分层的好处是当 Agent 走错路时你能一眼看出是决策错了还是执行错了。如果决策点输出的工具名就是错的那是规划问题如果决策点输出正确但执行点返回异常那是工具问题。混在一起埋点的话这个区分就做不出来了。还有一点给每个 run 起一个有意义的名字。默认名字往往是函数名看起来千篇一律。手动指定名字比如检索知识库重排候选生成最终答案追踪树读起来会顺畅很多。这个投入很小回报很大。3. 读懂一条 trace链路拆解与关键字段3.1 trace 树的结构与阅读顺序打开一条 trace你看到的是一棵可展开的树。根节点是这次请求的入口下面按时间顺序挂着各个 run。阅读顺序建议从上到下、从外到内先看根节点的总耗时和总 token判断这次请求整体是否正常再展开子节点看哪个环节耗时最长最后下钻到具体 run看输入输出是否符合预期。这里有个实用技巧按耗时排序。LangSmith 的界面支持按延迟排序子节点一眼就能找到瓶颈。我排查性能问题时第一步永远是看哪个 run 最慢。十有八九是某次模型调用或者某次检索拖了后腿而不是编排逻辑本身慢。另一个技巧是看 token 分布。如果某个 run 的 token 消耗异常高通常是 prompt 里塞了太多上下文。这时候就要回头检查检索环节是不是返回了过多文档或者历史对话是不是没有做截断。token 和延迟往往是联动的token 高通常延迟也高。3.2 输入输出字段里藏着的问题信号每个 run 的输入输出是最有信息量的部分。模型调用的输入是完整的 prompt输出是模型的原始返回。工具调用的输入是参数输出是工具的执行结果。这些字段要逐个核对。常见的信号有几个。第一prompt 里出现了重复内容说明上下文拼接逻辑有 bug可能把同一段历史拼了两次。第二工具返回是空或者报错但 Agent 没有正确处理继续往下走了。第三模型输出里包含了不该有的格式比如本该是 JSON 却返回了自然语言导致后续解析失败。这些问题在单步日志里也能看到但在 trace 里看更直观因为你能看到问题发生的前后文。比如工具返回为空你可以往上看是谁调用的、参数传对没有往下看这个空结果是怎么被消费的。这种上下文是排查的关键。3.3 元数据与标签的实战用法LangSmith 允许给 run 打标签、加元数据。很多人忽略这个功能觉得可有可无。但在实际项目里这是做筛选和对比的基础。我通常会给 run 加这几类元数据用户 ID、会话 ID、Agent 版本号、环境标识。有了这些你就能按用户筛选出问题请求按版本对比新旧表现按环境区分测试和生产数据。没有这些标签所有 trace 混在一起想找特定类型的请求只能靠肉眼翻。标签还有一个用法是做 A/B 对比。给两组实验打不同标签然后在平台上筛选对比它们的延迟、token、成功率。这比自己在代码里统计要方便得多而且能看到具体的 trace 差异不只是聚合数字。4. 用追踪数据反哺 Agent 优化4.1 从 trace 里挑出评测样本追踪数据最大的价值之一是它能变成评测集。你不需要凭空构造测试用例直接从真实请求里挑。挑的原则是覆盖典型场景、覆盖边界情况、覆盖已知的失败案例。具体做法是在平台上筛选出有代表性的 trace把它们加入数据集。LangSmith 支持把 trace 直接转成数据集样本输入输出都保留。这样构建评测集的速度比手工写快得多而且样本天然贴近真实分布。我的经验是每次线上出问题第一件事就是把那条 trace 存进数据集。日积月累数据集就成了一个真实的回归测试集。每次改完 Agent跑一遍这个集子就能知道有没有把老问题改回去。这比拍脑袋想测试用例靠谱得多。4.2 用评测结果定位是 prompt 问题还是工具问题跑完评测如果发现某些样本失败下一步是定位原因。这时候追踪数据又派上用场了。打开失败样本对应的 trace看它是在哪一步偏离了预期。如果是模型输出的格式不对那多半是 prompt 的问题需要调整指令或者加 few-shot 示例。如果是工具返回的结果不对那是工具本身或者参数传递的问题。如果是检索没召回相关文档那是检索策略的问题。这三类问题的修复方向完全不同定位准了才能对症下药。这里有个细节评测失败不一定意味着 Agent 有问题也可能是评测标准太严。比如模型输出意思对了但措辞不同字符串匹配就会判失败。所以评测最好用模型打分而不是精确匹配或者至少两者结合。这个坑我踩过一开始用精确匹配误报率高得离谱。4.3 延迟与成本的持续监控除了质量追踪数据还能监控延迟和成本。这两个指标直接关系到用户体验和运营成本但在开发阶段容易被忽略。延迟方面重点看 P95 和 P99而不是平均值。平均值会被大量快速请求拉低掩盖掉慢请求。慢请求往往集中在特定场景比如上下文特别长、工具调用特别多的时候。找到这些场景针对性优化效果比泛泛地优化明显得多。成本方面重点看 token 消耗的分布。如果少数请求消耗了大量 token那就要查这些请求有什么共同点。常见原因是历史对话没截断、检索返回文档过多、或者陷入了循环调用。这些问题在 trace 里都能看出来因为你能看到每一步的 token 消耗。5. 实际排查中容易踩的坑5.1 追踪数据缺失或不完整最常见的问题是追踪数据缺失。表现是 trace 树断了一截某个环节没有记录。原因通常有几个一是那个环节没埋点二是埋点了但上报失败三是异步调用没被正确追踪。异步调用是个大坑。如果你的 Agent 用了异步并发而埋点没有正确处理上下文传递子任务的 run 可能会丢失父节点信息变成孤立的 trace。解决方法是确保上下文在异步任务间正确传播具体做法依赖你用的框架但核心是别让上下文在 await 或线程切换时丢掉。上报失败也要留意。网络抖动、额度超限、序列化失败都可能导致数据丢失。建议在埋点处加日志记录上报是否成功。虽然有点啰嗦但排查数据缺失时能省很多时间。5.2 敏感信息泄露的风险追踪数据里会包含完整的 prompt 和工具返回这里面可能有用户隐私、内部文档、密钥等敏感信息。如果这些数据被完整上报到第三方平台是有合规风险的。处理方式有几种。一是脱敏在上报前把敏感字段替换掉。二是过滤某些类型的 run 干脆不上报。三是自建部署把数据留在自己的环境里。选哪种取决于你的合规要求和数据敏感程度。我的建议是至少在接入前梳理一遍数据流搞清楚哪些字段会包含敏感信息。别等到出了问题才回头补那时候数据可能已经出去了。脱敏逻辑最好做成统一的中间层而不是散落在各个埋点处否则容易漏。5.3 采样策略与调试需求的矛盾前面提到生产环境要采样但采样和调试是有矛盾的。采样率低的时候出问题的请求可能刚好没被采到你就失去了排查依据。解决办法是分层采样正常请求低采样异常请求全采样。异常包括报错、超时、返回空、用户负反馈等。这样既控制了数据量又保证了问题请求有据可查。实现上需要在埋点处判断请求状态动态决定是否上报。另一个办法是保留一个最近 N 条的环形缓冲不管采样率如何最近的请求总是保留。这样即使采样率很低你也能看到最近发生了什么。这个策略在排查突发问题时特别有用。6. 把追踪能力沉淀成团队习惯6.1 建立 trace 命名与标签规范一个人用追踪工具和团队用是两回事。团队用的话必须统一规范否则每个人的 trace 命名五花八门筛选和对比都做不了。规范至少要覆盖三点run 的命名规则、标签的取值集合、元数据的必填字段。命名规则比如模块名-操作名标签比如固定几个枚举值而不是自由填写元数据比如用户 ID 和版本号必填。这些规范写进文档新同学接入时照着做。规范的价值在协作时体现。当所有人都按同一套规则埋点你就能跨人、跨模块地筛选和分析。反之如果各埋各的追踪数据就是一堆孤岛价值大打折扣。6.2 把 trace 链接进 issue 和复盘排查问题时把相关的 trace 链接贴进 issue 或者复盘文档是个很好的习惯。这样后来的人不用重新复现直接点开链接就能看到当时的现场。这个习惯的另一个好处是它倒逼你把 trace 保留好。如果 trace 过期了链接失效复盘时就抓瞎了。所以要么延长保留期要么在贴链接的同时把关键信息截图存档。我倾向于两者都做链接方便下钻截图防止失效。6.3 定期回顾追踪数据发现系统性问题追踪数据不只是用来救火的还能用来发现系统性问题。定期回顾比如每周看一次往往能发现一些平时没注意到的模式。比如某个工具的错误率在缓慢上升单看某一天不明显拉长时间看趋势就出来了。再比如某类请求的延迟在特定时段变高可能和外部依赖的负载有关。这些问题不会自己暴露需要主动去看。回顾的时候重点看几个指标错误率、延迟分布、token 分布、工具调用成功率。这几个指标的变化往往能反映出系统健康度的变化。发现异常就深挖对应的 trace通常能找到根因。追踪这件事做和不做差别很大做得好和做得一般差别也很大。工具本身不复杂难的是把它用成习惯用成团队协作的一部分。我自己的体会是刚开始接入时会觉得多了一层负担但一旦用顺了离开它反而不会调试了。
