【三个月 AI Agent 实战学习】Day 33：LangSmith 调试与监控 —— 可视化追踪 Agent 的每一步

Day 33：LangSmith 调试与监控 —— 可视化追踪 Agent 的每一步

欢迎来到第三十三天！在前面的学习中，我们通过verbose=True和自定义回调来观察 Agent 的执行过程。但这种方式输出冗长、难以检索，也无法直观看到 Token 消耗、延迟和调用链。今天我们将学习LangSmith——LangChain 官方的调试与监控平台。它能自动记录每一次 LLM 调用、工具执行和 Agent 步骤，并以可视化面板呈现，让你像使用 Chrome DevTools 一样调试 Agent。如果无法访问 LangSmith，我们也会提供LangFuse作为备选方案。

一、今日学习目标

1. 理解 LangSmith 的作用：追踪、调试、评估和监控 LLM 应用。
2. 学会注册 LangSmith 并获取 API Key，配置环境变量实现自动追踪。
3. 掌握在 LangChain 代码中启用 LangSmith 追踪的方法（通常只需设置环境变量）。
4. 学会在 LangSmith 面板中查看 Trace、Run、Span，分析每个步骤的输入输出、Token 消耗和延迟。
5. 了解 LangFuse 作为开源替代方案的基本用法，以便在无法使用 LangSmith 时也能调试。
6. 能够利用追踪信息定位 Agent 中的性能瓶颈和错误。

二、详细实现步骤

步骤 1：注册 LangSmith 并获取 API Key

1. 访问 https://smith.langchain.com/。
2. 使用 Google 账号或邮箱注册（如果网络受限，可以尝试使用 LangFuse，见步骤 7）。
3. 登录后，点击左下角的Settings，然后选择API Keys。
4. 点击Create API Key，复制生成的 Key（格式类似lsv2_pt_...）。
5. 同时记录你的Project Name，可以新建一个项目，例如ai-agent-learning。

步骤 2：配置环境变量

LangChain 会自动读取以下环境变量来启用 LangSmith 追踪：

LANGCHAIN_TRACING_V2=trueLANGCHAIN_ENDPOINT=https://api.smith.langchain.comLANGCHAIN_API_KEY=你的_LangSmith_API_KeyLANGCHAIN_PROJECT=ai-agent-learning

你可以将这些写入.env文件，或直接在终端中导出。如果使用.env，确保在代码中load_dotenv()能加载到。

importosfromdotenvimportload_dotenv load_dotenv()# 确认环境变量已加载（可选）print(os.getenv("LANGCHAIN_TRACING_V2"))print(os.getenv("LANGCHAIN_PROJECT"))

步骤 3：在现有 Agent 中启用追踪

LangSmith 的集成非常简单：只要环境变量设置正确，无需修改任何业务代码，所有 LangChain 组件的调用都会被自动追踪。

我们以 Day 24 的数学专家 Agent 为例，重新运行一次：

importosfromdotenvimportload_dotenvfromlangchain_openaiimportChatOpenAIfromlangchain_core.toolsimporttoolfromlangchain.agentsimportcreate_react_agent,AgentExecutorfromlangchain_core.promptsimportPromptTemplate load_dotenv()llm=ChatOpenAI(model="deepseek-chat",api_key=os.getenv("DEEPSEEK_API_KEY"),base_url="https://api.deepseek.com",temperature=0.1)@tooldefcalculator(expression:str)->str:"""计算数学表达式，支持加减乘除和括号。"""try:allowed=set("0123456789+-*/(). ")ifnotset(expression).issubset(allowed):return"错误：表达式包含非法字符"returnstr(eval(expression))exceptExceptionase:returnf"错误：{e}"@tooldefsearch(query:str)->str:"""搜索信息，输入关键词或问题，返回相关答案。"""knowledge={"北京天气":"北京今天晴，26°C，湿度 40%。","中国首都":"中国的首都是北京。"}forkey,valueinknowledge.items():ifkeyinquery:returnvaluereturn"未找到相关信息。"react_template="""你是一个智能助手，可以使用以下工具： {tools} 工具名称列表：{tool_names} 使用格式： 问题：{input} 思考：{agent_scratchpad} 行动：工具名 行动输入：输入 观察：结果 ...（重复） 思考：我现在知道最终答案了 最终答案：回答 开始！ 问题：{input} 思考：{agent_scratchpad}"""prompt=PromptTemplate.from_template(react_template)agent=create_react_agent(llm,[calculator,search],prompt)executor=AgentExecutor(agent=agent,tools=[calculator,search],verbose=False,# 关闭本地 verbose，改用 LangSmith 查看handle_parsing_errors=True,max_iterations=5)result=executor.invoke({"input":"请计算 (12 + 7) * 3，然后搜索北京天气"})print("最终答案：",result["output"])

运行后，打开 LangSmith 网站，进入你的项目ai-agent-learning，你会看到一个新的 Trace 记录。

步骤 4：解读 LangSmith 面板

在 LangSmith 中，你会看到以下关键信息：

• Trace：一次完整的 Agent 调用，包含所有步骤。
• Run：Trace 中的每个节点，例如 LLM 调用、工具执行、Agent 决策。
• 输入/输出：每个 Run 的输入提示词和输出结果。
• Token 消耗：每个 LLM 调用的 prompt tokens、completion tokens 和总 tokens。
• 延迟：每个步骤的耗时，帮助你定位性能瓶颈。
• 错误信息：如果某一步失败，会显示异常堆栈。
• 元数据：模型名称、温度、工具名称等。

你可以点击任意 Run 查看详细信息。例如，点击calculator工具，可以看到它的输入"(12 + 7) * 3"和输出"57"。点击 LLM Run，可以看到完整的提示词（包括 scratchpad）和模型回复。

步骤 5：利用追踪优化 Agent

通过 LangSmith，你可以快速发现以下问题：

• Token 消耗过高：检查哪些 LLM 调用消耗了大量 Token，是否因为历史消息过长或提示词冗余。
• 工具调用错误：查看工具输入是否符合预期，参数是否缺失。
• 死循环：观察 Agent 是否在重复调用同一个工具，以及每次的输入是否相同。
• 延迟瓶颈：哪个步骤耗时最长，是 LLM 生成慢还是工具执行慢。

例如，如果你发现 Agent 反复调用search但查询词几乎一样，说明提示词可能需要调整，要求模型在重复查询时改变策略。

步骤 6：添加自定义元数据和标签

你可以在调用时添加metadata和tags，方便在 LangSmith 中过滤和分组：

result=executor.invoke({"input":"计算 5 * 8"},config={"metadata":{"user_id":"user_123","session":"test_1"},"tags":["math","test"]})

这样在 LangSmith 中可以根据标签筛选 Trace。

步骤 7：备选方案 —— LangFuse

如果无法访问 LangSmith，可以使用LangFuse（开源、可自托管）。它同样支持 LangChain 自动追踪。

1. 注册 LangFuse 云账号：https://cloud.langfuse.com/，或使用 Docker 自托管。
2. 获取 Public Key 和 Secret Key。
3. 安装 LangFuse SDK：

pipinstalllangfuse

4. 设置环境变量：

LANGFUSE_PUBLIC_KEY=pk-lf-...LANGFUSE_SECRET_KEY=sk-lf-...LANGFUSE_HOST=https://cloud.langfuse.com# 或自托管地址

5. 在代码中初始化 LangFuse 回调（LangChain 会自动集成）：

fromlangfuse.callbackimportCallbackHandler langfuse_handler=CallbackHandler()result=executor.invoke({"input":"计算 5 * 8"},config={"callbacks":[langfuse_handler]})

然后登录 LangFuse 面板查看 Trace。

步骤 8：本地日志作为最后手段

如果连 LangFuse 也无法使用，可以继续使用 Day 25 的自定义回调，将日志写入文件。但 LangSmith/LangFuse 的可视化能力是本地日志无法比拟的。

三、常见问题与调试

Q1：设置了环境变量但 LangSmith 没有记录。
→ 检查：

• LANGCHAIN_TRACING_V2=true是否设置。
• API Key 是否正确，是否有空格。
• 项目名称是否设置。
• 是否需要重启 Python 进程（环境变量在启动时读取）。
• 网络是否能访问api.smith.langchain.com。

Q2：LangSmith 显示 “No traces found”。
→ 确认代码中是否使用了 LangChain 组件（如ChatOpenAI、AgentExecutor）。直接使用openaiSDK 的调用不会被 LangSmith 追踪。

Q3：Trace 中看不到工具调用的详细信息。
→ 确保工具是通过@tool装饰器定义的，并且被传递给了AgentExecutor。LangSmith 会自动捕获工具执行。

Q4：Token 消耗统计不准确。
→ LangSmith 从 API 响应中读取 usage 信息。如果模型提供商不返回 usage（部分兼容 API 可能不返回），则无法统计。DeepSeek 通常返回 usage，应该能正常显示。

Q5：LangSmith 是否收费？
→ LangSmith 提供免费额度（每月 5000 次 trace），对个人学习足够。超出后需要付费。LangFuse 开源版可自托管，完全免费。

Q6：如何保护隐私？
→ LangSmith 会上传提示词和输出到云端。如果涉及敏感数据，建议使用自托管的 LangFuse，或在代码中脱敏。也可以设置LANGCHAIN_HIDE_INPUTS=true等环境变量隐藏内容。

四、今日总结与作业

今天你完成了：

• ✅ 注册并配置了 LangSmith，实现了 Agent 的自动追踪。
• ✅ 学会了在 LangSmith 面板中查看 Trace、Run、Token 消耗和延迟。
• ✅ 了解了如何利用追踪信息定位性能瓶颈和错误。
• ✅ 掌握了 LangFuse 作为备选方案的基本用法。
• ✅ 能够通过自定义元数据和标签组织追踪记录。

今日作业（必做）：

1. 使用 LangSmith 追踪 Day 31 的“书童机器人”，进行 5 轮对话。在 LangSmith 中查看每次 LLM 调用的 Token 消耗，计算总消耗，并观察历史消息如何随对话增长。
2. 在 LangSmith 中找到一个工具调用错误的 Trace（可以故意构造，例如让计算器收到非法表达式），截图或记录错误信息，分析 Agent 是如何处理这个错误的。
3. 尝试为你的 Agent 添加自定义元数据（如user_id、session_id），并在 LangSmith 中按标签过滤。
4. （思考题）如果 LangSmith 显示某个 LLM 调用耗时超过 10 秒，你会从哪些方面排查原因？请列出至少三个可能的原因和对应的优化方向。

明日预告：我们将学习 Routing（路由）—— 让 Agent 根据用户意图将请求分发给不同的处理链，这是构建复杂多技能 Agent 的关键技术。

有任何问题欢迎随时提问！