使用 LangSmith 专业调试 AI Agent：追踪、评估与问题定位

引言：为什么 Agent 一复杂，日志就开始不够用了？

在前一篇《LangGraph 与 ReAct Agent 调试技巧》中，我们已经讲过：

• print
• logging
• stream_mode=["updates", "values", "debug"]
• interrupt_before/interrupt_after
• time-travel 回放

这些方法已经足够帮你排掉 80% 的问题。

但当你的 Agent 开始变复杂以后，你很快会发现：

单靠日志，已经不够了。

例如：

• 一个 Agent 里有 10 个节点、5 个 Tool
• 一个用户问题，会产生几十次模型调用
• 同一个问题，不同时间运行结果不一样
• 线上用户反馈“Agent 卡住了”，但你根本拿不到当时现场
• Tool 调了，但你不知道到底是哪一步开始偏
• Token 花得很快，但你不知道浪费在哪

这时候，普通日志会遇到三个根本问题：

1. 日志太碎
2. 无法把一次完整执行串起来
3. 无法比较不同运行之间的差异

于是你会进入一种非常痛苦的状态：

日志很多 但还是不知道问题在哪

这也是为什么，Agent 项目一旦进入真实开发阶段，就几乎一定会用到：

LangSmith

LangSmith 是 LangChain / LangGraph 官方提供的 AI 应用调试、Tracing、评估平台。它最大的价值不是“再多打一层日志”，而是：

把一次 Agent 执行，从黑盒，变成一条完整、可追踪、可回放、可比较的轨迹。

简单理解，你可以把它看成：

• AI Agent 版的 APM
• AI Agent 版的链路追踪
• AI Agent 版的 Jaeger / Zipkin / SkyWalking

只不过，它追踪的不是 HTTP 请求，而是：

Prompt → 模型调用 → Tool 调用 → State 更新 → 最终输出

这篇文章，我们就来完整讲清楚：

1. LangSmith 到底是什么
2. 为什么单靠日志不够
3. 如何一行代码开启 Tracing
4. 如何用 LangSmith UI 看 Trace、Token、Latency、Tool
5. 如何用 Polly 聊天式排查 Agent 问题
6. 如何定位“工具没返回”“State 没更新”“死循环”等顽固 bug

一、LangSmith 是什么？

一句话总结：

LangSmith 是专门给 AI Agent / LLM 应用做调试和评估的平台。

如果你熟悉传统后端，你可以这样类比：

LangSmith 最核心的概念，是把一次 Agent 执行，拆成一棵树。

例如一个 ReAct Agent：

用户问题 └─ LLM 推理 └─ Tool: get_weather └─ Tool 返回 Observation └─ LLM 再推理 └─ Tool: calculator └─ 最终答案

在日志里，这可能只是几十行混乱输出。

但在 LangSmith 里，它会变成一棵可以展开、点击、查看每一步细节的 Trace Tree。

这也是它最大的价值：

它让你知道，Agent 到底是怎么一步一步走到这个结果的。

二、为什么单靠日志不够？

很多工程师第一次接触 LangSmith，都会想：

我已经有 print 和 logging 了，还需要这个吗？

答案通常是：

当你的 Agent 超过 3 个节点以后，就非常需要。

因为日志天生有三个问题。

1. 日志是线性的，但 Agent 是树状的

日志通常长这样：

[tool_node] input=... [tool_node] output=... [llm_node] input=... [llm_node] output=...

你很难看出：

• 谁是谁的父节点
• 哪一次 Tool 调用属于哪一次模型推理
• 当前调用到底在第几轮循环里

而 LangSmith 会自动把它组织成：

Agent ├─ LLM Call #1 ├─ Tool Call #1 ├─ LLM Call #2 └─ Final Output

这对于 ReAct、LangGraph、多 Agent 特别重要。

2. 日志不能方便地比较两次运行

很多 Agent 问题不是“永远错”，而是：

同一个输入，这次对，下次错。

这时候你最想做的是：

• 把两次运行放在一起
• 看看到底哪一步开始不一样

普通日志很难做到。

而 LangSmith 支持直接比较两个 Trace。

3. 日志通常没有 Token、Latency、Cost

你可能会发现：

• 为什么这个 Agent 这么慢？
• 为什么 token 花得特别多？
• 是不是某一步循环太多次？

这些问题，普通日志几乎回答不了。

而 LangSmith 会自动展示：

• 每一步 latency
• 每一步 token 数
• 模型花费
• Tool 执行耗时

所以你不仅能排“对不对”，还能排“慢不慢”“贵不贵”。

三、一行代码开启 Tracing：LangGraph 自动支持

LangSmith 最爽的一点是：

接入特别简单。

尤其是 LangGraph / LangChain 项目，很多情况下只需要环境变量。

1. 安装

pipinstall-Ulangsmith

2. 配置环境变量

exportLANGCHAIN_TRACING_V2=trueexportLANGCHAIN_API_KEY=你的_langsmith_keyexportLANGCHAIN_PROJECT=my-agent-project

如果你用.env：

LANGCHAIN_TRACING_V2=true LANGCHAIN_API_KEY=你的_langsmith_key LANGCHAIN_PROJECT=my-agent-project

然后在代码里：

fromdotenvimportload_dotenv load_dotenv()

就可以了。

对于 LangChain / LangGraph，大多数调用都会自动被 Trace。

例如：

graph.invoke(input_data)

执行完以后，你去 LangSmith UI，就会看到完整 Trace。

3. 为什么说“LangGraph 自动支持”？

因为 LangGraph 的节点、边、State，本身就很适合被记录成一棵 Trace Tree。

所以你不需要手工埋点每个节点。

LangSmith 会自动记录：

• 当前执行了哪个 node
• node 输入是什么
• node 输出是什么
• 下一个 node 是谁

这也是它比纯日志方便很多的原因。

四、LangSmith UI 实战：你真正应该看什么？

很多人第一次打开 LangSmith，会被一堆字段吓到。

实际上，真正最值得看的只有四类东西：

1. Trace Tree
2. Token 与 Cost
3. Latency
4. Tool 调用详情

1. Trace Tree：先看执行路径

进入一次 Run 后，最先看的永远是左边的 Trace Tree。

它会像这样：

AgentExecutor ├─ ChatOpenAI ├─ get_weather ├─ ChatOpenAI ├─ calculator └─ ChatOpenAI

你首先要回答的问题是：

它有没有按我预期的顺序执行？

例如：

• 有没有调 Tool
• Tool 调的是不是正确的
• 有没有多走了一轮
• 有没有进入死循环

如果执行路径已经不对，那后面不用再看 Prompt 了。

2. Token 使用：为什么 Agent 这么贵？

很多人第一次做 Agent，都会发现：

明明只问了一句话，怎么花了这么多 token？

LangSmith 会帮你直接展示：

• Prompt tokens
• Completion tokens
• Total tokens

你会很容易发现：

• 某个节点 Prompt 太长
• Memory 把太多历史带进去了
• Agent 在循环里重复调用同一个模型

例如：

LLM Call #1: 1200 tokens LLM Call #2: 1500 tokens LLM Call #3: 1700 tokens

那大概率说明：

State / messages 在不断膨胀。

这也是定位 Memory 失控最有效的方法之一。

3. Latency：Agent 为什么这么慢？

很多时候，用户觉得 Agent “不好用”，其实不是因为结果错，而是因为太慢。

LangSmith 会告诉你：

• 哪一步最慢
• 是模型慢，还是 Tool 慢
• 是某个节点卡住了，还是循环太多次

例如：

get_weather: 50ms calculator: 5ms ChatOpenAI: 8s

那你立刻就知道：

问题不在 Tool，而在模型。

如果你看到：

同一个节点重复执行了 6 次

那说明：

Agent 很可能陷入循环。

4. Tool 调用详情：最容易藏 bug 的地方

很多 Agent 问题，其实最后都会落到 Tool 上。

例如：

• Tool 名字不清
• 参数没提取对
• Tool 返回值没写对
• Tool 返回了，但下一步没读

在 LangSmith 里，你可以直接点开某个 Tool Run，看到：

Tool Name: get_weather Input: {"city": "北京"} Output: "北京今天晴天，25度"

如果参数不对、返回为空、或者输出字段错了，这里会非常明显。

五、Polly：直接问“这个 Agent 为什么错了？”

这是 LangSmith 里 2026 年非常值得写的一部分。

LangSmith 现在内置了一个 AI 调试助手：

Polly

你可以把它理解成：

一个会帮你读 Trace 的 AI 工程师。

你不需要自己一层一层点。

你可以直接问：

为什么这个 Agent 没有调用 get_weather？

或者：

为什么它一直循环？

甚至：

这个 Trace 里，最可能的问题在哪？

Polly 会自动分析整条 Trace，并给你类似：

该 Agent 没有调用 get_weather，因为 system prompt 没有明确要求必须使用工具。 模型直接根据常识回答。

或者：

Agent 在 tool_node 和 llm_node 之间循环了 5 次。 因为 state["done"] 从未被设置为 True。

这对于复杂 Agent 来说，非常有价值。

因为很多时候，问题并不是“看不到”，而是：

Trace 太长，人已经看不过来了。

而 Polly 相当于帮你先读一遍。

六、案例：定位“工具结果没返回”

这是最常见的一类问题。

现象：

Tool 已经执行了 但最终答案还是瞎猜

你打开 LangSmith Trace，会看到：

Tool: get_weather Output: 北京今天晴天，25度

说明 Tool 本身没问题。

接着你再看下一轮 LLM 输入。

结果发现：

messages 里没有 ToolMessage

这说明：

Tool 虽然执行了，但 Observation 没被写回上下文。

最终模型等于“没看到工具结果”。

问题就定位到了 Tool Node。

七、案例：定位“State 没更新”

例如：

Graph 里 weather_node 已经跑完 但下一步 answer_node 却拿不到 weather

在 LangSmith Trace 里，你会看到：

weather_node output: { "result": "北京25度" }

而 answer_node 期待的是：

state["weather"]

于是问题就很明显：

字段名写错了。

日志里你可能很难第一时间发现。

但在 LangSmith 的输入 / 输出面板里，一眼就能看出来。

八、案例：定位“无限循环”

无限循环是 Agent 最痛苦的问题之一。

例如 Trace 看起来像：

llm_node → tool_node → llm_node → tool_node → llm_node → tool_node

一直重复。

这时候你可以直接看 Trace Tree。

如果发现：

• 相同节点重复出现很多次
• 每次输入几乎一样
• 每次输出也几乎一样

那大概率就是：

停止条件没有触发。

你再去看对应节点输出。

通常会发现：

state["done"]=False

永远没变。

或者模型每次都在说：

我还需要继续查询。

这说明 Prompt 没明确告诉模型：

什么时候应该停止。

九、为什么 LangSmith 特别适合复杂 Agent？

如果你的 Agent 只是：

Prompt → 模型 → 输出

那 print 和 logging 可能已经够了。

但如果你开始做：

• ReAct
• 多 Tool
• LangGraph
• 多 Agent 协作
• Memory
• 长时间运行

你会发现：

问题已经不是“有没有日志”，而是“有没有办法把整个执行过程组织起来”。

而 LangSmith 最强的地方就在这里：

• 它能自动记录每一步
• 能自动关联上下游
• 能直接比较两次运行
• 能统计 Token、Latency、Cost
• 能帮你找到真正的问题开始于哪里

一句话说：

LangSmith 不是为了让你“看更多日志”，而是为了让你“终于能看懂日志”。

十、给工程师的实战建议

最后给你几条特别实用的经验。

1. 不要等 Agent 出问题了，才接 LangSmith

最好的做法是：

项目一开始就接。

因为很多问题，只有在第一次出错时，Trace 才最完整。

2. 每个重要版本，都保留一个固定测试集

例如：

• 天气问题
• 工具调用问题
• Memory 问题
• 多轮对话问题

每次改 Prompt、改 Tool、改 Graph 后，都重新跑一遍。

这样你才能知道：

是不是修了一个 bug，又引入了另一个 bug。

3. 调试时，先看 Trace Tree，再看 Prompt

很多人一上来就怀疑 Prompt。

但真正的问题，经常更简单：

• Tool 没调
• 参数错了
• State 没写
• 边连错了

所以一定先看执行路径。

4. Polly 适合快速定位，但不要完全依赖

Polly 非常适合：

• 快速读长 Trace
• 给出第一层怀疑

但最后还是建议你自己打开关键节点确认。

因为真正的复杂 bug，最终还是要落到：

• Prompt
• Tool
• State
• Graph

这些具体实现上。

结语

一句话总结：

当 Agent 进入真实项目后，最难的不是“写”，而是“知道它为什么错”。

而 LangSmith 真正提供的，不只是日志，而是一整套：

• Tracing
• 可视化
• Token / Cost / Latency 分析
• 多次运行比较
• AI 辅助排障

它会让你第一次真正看见：

Agent 到底是如何一步一步走向错误，或者走向正确。

当你能看见它的轨迹时，复杂 Agent 才真正开始变得可维护。

📎 相关资源

• j-langchain GitHub：https://github.com/flower-trees/j-langchain