LangSmith 调试 LLM agent：把每个 prompt / 工具调用都看清楚

起因

写了一个 LangChain agent 帮用户查数据库 + 写 SQL + 解释结果，
跑起来时不时给出乱七八糟的答案。问题可能出在：

• 哪一步的 prompt 让 LLM 跑偏？
• 调了什么 tool、tool 返回了什么？
• 重试了几次？
• 哪段花了最多 token / 最长时间？

print(intermediate_steps) 看不出来。LangSmith 是 LangChain 团队的可观测平台，
自动把 chain / agent 的每一次执行都记下来，UI 时间线展开看。

解决方案

注册 + 装

注册 smith.langchain.com（免费层个人项目够），
拿 API key。

uv add langsmith
export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_API_KEY=ls__xxxxxxxx
export LANGCHAIN_PROJECT=my-agent-debug

就这样。LangChain 自动把所有 chain / agent 执行 trace 上报到 LangSmith。
不需要改任何代码。

看 trace

进 LangSmith UI → 选 project → 看 trace 列表：

Run name              Duration   Tokens     Status
sql_agent.invoke      5.3s       2,341      success
sql_agent.invoke      12.1s      8,902      error
...

点进任意 run：

└─ sql_agent (5.3s, 2341 tokens)
   ├─ planner (1.2s, 540 tokens)
   │  └─ ChatOpenAI (1.1s, 540 tokens)
   │     ▶ prompt: "You are a SQL planner. Decide..."
   │     ◀ output: {"action": "run_sql", "sql": "SELECT ..."}
   ├─ tool: run_sql (0.3s)
   │  ▶ input: SELECT count(*) FROM users WHERE ...
   │  ◀ output: [{"count": 142}]
   └─ responder (3.8s, 1801 tokens)
      └─ ChatOpenAI (3.7s, 1801 tokens)
         ▶ prompt: "Given the query result, answer..."
         ◀ output: "总共有 142 个符合条件的用户。"

每一层展开看完整 prompt + completion + tokens + latency。

找出"为什么这次出错"

filter "status=error" 看所有失败 run。点进去：

└─ sql_agent (failed at responder)
   ├─ planner ✓
   ├─ run_sql ✗ (ERROR: column "user_typ" does not exist)
   └─ ...

清楚看到 SQL agent 拼错列名（应该是 user_type）。回头改 prompt 加
schema 提示。

A/B 对比 prompt

LangSmith 有 "Datasets" + "Compare experiments"：

1. 创建 dataset：10-20 个典型 query + 期望答案
2. 跑 prompt v1：run_on_dataset(dataset_name, prompt_v1_chain)
3. 跑 prompt v2：同上
4. UI 对比每个 input 上 v1 vs v2 的输出 + 自动 eval 分数

from langsmith import Client
client = Client()

dataset = client.create_dataset('sql_agent_eval')
client.create_example(
    inputs={'query': '过去 7 天注册的用户数'},
    outputs={'expected': '~150'},
    dataset_id=dataset.id,
)

from langchain.smith import RunEvalConfig
client.run_on_dataset(
    dataset_name='sql_agent_eval',
    llm_or_chain_factory=lambda: sql_agent_v2,
    evaluation=RunEvalConfig(evaluators=['qa', 'context_qa']),
)

LangSmith 自动用 GPT-4 当 judge 评分。

prompt hub

LangChain Hub 集成在 LangSmith：

from langchain import hub
prompt = hub.pull('rlm/rag-prompt')

社区 prompt 模板，pull + 改自己版本 + push 回去（你的私有 namespace）。

用于 production 监控

不止 dev 用：

import os
os.environ['LANGCHAIN_TRACING_V2'] = 'true'
os.environ['LANGCHAIN_PROJECT'] = 'prod'   # 区分环境

production 上跑的每个 trace 都收集。看：

• 每天调用量
• 每个 chain 的 P50 / P95 延迟
• token 消耗趋势
• error 率 + 错误类型分布

可以接 alert：当 error rate > 5% 邮件通知。

与替代品对比

LangChain 项目用 LangSmith 最方便；不想绑定平台用 Langfuse 自托管。

效果

• agent 失败率 12% → 4%，靠看 trace 改 prompt 一周搞定
• "为什么这次跑出 X" 的问题从"猜 + 加 print"变成 "去 LangSmith 看一下"
• 找到一个 prompt 让 token 消耗减半（trace 里看到 LLM 反复重复同样
  上下文）
• 团队 review prompt 改动有了客观依据（运行某 dataset 对比 v1/v2 分数）

踩过的坑

1. traces 含敏感数据上 cloud：用户邮箱 / 手机号都进 prompt 时
   隐私问题。开 LANGCHAIN_TRACING_V2=false 临时关，或者 enterprise
   自托管。

2. 大批量 run 上报慢：默认同步上报，每个 run 加 50-100ms。设
   LANGCHAIN_CALLBACKS_BACKGROUND=true 异步上报。

3. trace 嵌套太深：复杂 agent 数十层调用，UI 加载慢。用 tag /
   metadata 标记关键步骤再筛选。

4. eval 用 GPT-4 评分：成本可能比被评模型还高。先小 dataset
   验证 eval 设置对，再扩规模。

5. 本地 LLM trace：用 Ollama / vLLM 跑本地模型时，把 ChatOpenAI
   的 base_url 改本地即可，trace 一样上报。注意 token 计数对本地
   模型不准。