用 LangSmith 追踪打通多编码 Agent 调试

LangChain 工程师 Hari Harish 在 7 月 14 日发布工程实践长文,讲述用 LangSmith 追踪来调试多厂商编码 Agent。故事从他一次亲身卡壳开始:让编码 Agent 给报表接口加 CSV 导出,子 Agent 被派去处理分页,但它翻出了一个老旧工具,按 offset 而不是游标分页,结果一次又一次偏离需求,改提示、再跑、再错,终端里满是自信却错乱的回答。作者事后回看 trace 才发现,在上下文交接时,父 Agent 指向了代码库另一处已弃用的分页助手,只需在提示里强调这个旧实现即可,完全不必反复复述需求。

编码 Agent 已成为日常工程栈的一部分,开发者会按任务挑工具:Claude Code 跑 Shell、Cursor 改内联、Copilot 审 PR、Codex 起草工作流。问题是各家记录方式不一致,有的暴露 hook,有的发 OpenTelemetry,有的依赖插件,字段、术语、层级也各不相同。同样是「一次工具调用」,在 Codex 和 Cursor 里几乎是两套数据结构,跨 Agent 排查失败、统计耗时或成本时,要在多套心智模型之间切换。

LangSmith 的解法是给主流编码 Agent 套上一层统一可观测层,目前已支持 Claude Code、Codex、Cursor、GitHub Copilot Chat、Pi、OpenCode 以及 DeepAgents Code(dcode)。这些工具的会话会以标准化 trace 形式落到 LangSmith,可被检索、可被分享,且关键信息会自动脱敏。Trace 中包含用户与助手轮次、模型调用的输入输出、缓存、token 与成本、工具调用、Shell 命令、MCP 活动、子 Agent 调用、错误与重试,以及耗时与元数据,基本覆盖了从模型层到运行时层的全部关键节点。

在调试动作上,作者演示了三步典型路径:先按 thread_id 过滤,按时间线回放整轮会话;再下钻到失败点,例如一次测试失败后 Agent 选择直接改文件而不是重新评估逻辑,导致表面「通过」;最后把这次踩坑固化为可复用的 Skill,让同一个教训在不同 Agent 间生效,顺便进入评测体系验证是否真的修好,以及是否出现回归。

更大的价值在于跨 Agent 视角:统一 schema 让 Claude Code、Cursor、OpenCode 的会话在 LangSmith 中拥有相同的核心字段,可以横向比较同一工作流下不同模型的表现、发现隐式的子 Agent 派发、筛出需要人工复核的会话,以及按延迟、成本、token 用量起步做成本治理。文章最后给出一份集成清单,按官方步骤接好之后,日常使用编码 Agent 时无需额外埋点,会话会直接以 trace 形式出现,这套做法同时也是从单次修复走向系统性 Agent 改进的入口。

要点

• LangSmith 已原生支持 Claude Code、Codex、Cursor、GitHub Copilot Chat、Pi、OpenCode、DeepAgents Code 等主流编码 Agent,会话自动以标准化 trace 形式汇聚。
• Trace 覆盖用户轮次、模型调用、token 与成本、工具调用、Shell、MCP、子 Agent 派发、错误与重试,以及耗时与元数据,可按 thread_id 完整回放。
• 调试流程分三步:Reconstruct 还原整轮会话、Debug 下钻失败原因、Improve 将踩坑固化为跨 Agent 复用的 Skill 并纳入评测。
• 统一 schema 让团队能横向对比不同 Agent 在同一工作流上的表现,发现隐性子 Agent 派发,筛选需要复核的会话。
• 按延迟、成本、token 用量过滤 trace,是从单次修复迈向成本治理与系统性 Agent 改进的起点。