一文搞懂 LangSmith：从可观测到 Studio 调试，让 LLM Agent 告别黑盒

发表于最近更新于最近

作者 KennethCheng

361~465 分钟 阅读

作为 LangChain 团队三大核心产品之一，LangSmith 提供观察、调试和部署 LLM 应用的统一平台。本文带你从入门到 Studio 实战，彻底搞懂 LangSmith 的使用方式。

一、初识 LangSmith

当我们成功构建一个 Agent 后，常常会被这些问题困扰：

这个请求到底经历了哪些步骤？工具被调用了几次？
不同版本的提示词，效果到底差在哪？
上线后如何持续监控线上表现？

LangSmith 就是为了解决这些痛点而生的。它提供请求追踪、输出评估、提示词测试、部署管理等一站式能力，让我们能够清晰地看清 Agent 内部到底发生了什么。

LangSmith 的整体定位

可以看到，LangSmith 围绕 LLM 应用的生命周期提供了四大核心能力。

二、四步开启 LangSmith 之旅

从零到使用 LangSmith，只需要四步：

接下来按顺序拆解每一步。

三、注册与 API Key 创建

3.1 注册登录

访问 https://smith.langchain.com
可用 Google / GitHub / Discord / 邮箱注册登录
顶部可切换 Data Region（如 US）

3.2 创建 API Key

入口：Settings -> API docs -> + API Key

需要填写：

字段	说明
Description	Key 的用途描述
Key Type	`Personal Access Token`（个人）/ `Service Key`（CI / 自动化）
Default Workspace	默认工作空间（无 `x-tenant-id` header 时使用）
Expiration Date	`Never` / `30d` / `90d` / `1 year` / `Custom`

生成后点击 Copy 复制 Key（形如 lsv2_pt_...），务必妥善保存，弹窗关闭后将无法再次完整查看。

四、基于 LangSmith 观察 Agent 工作流

LangSmith 提供端到端的轨迹追踪：每次请求都会生成一个 Trace，Trace 内部按调用顺序包含若干 Run（工具执行、LLM 调用、状态更新等）。

4.1 设置环境变量

LANGSMITH_TRACE=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_API_KEY=lsv2_...

4.2 构建 Agent 并调用

from langchain.agents import create_agent
from langchain.agents.middleware import TodoListMiddleware

agent = create_agent(
    model=model,
    tools=[internet_search, calculate],
    middleware=[TodoListMiddleware()],
)

res = agent.invoke({"messages": [
    """搜索一下2025年deepseek公司全年动态，然后为我生成一份简洁的年度报告。"""
]})

4.3 Trace 结构解读

调用完成后，LangSmith 会生成如下结构的轨迹：

可以看到一次完整的请求被拆成了 model → tools → model → tools 的循环结构，每一步都能看到：

耗时、Token 数
Input / Output 的完整 JSON
Run / Feedback / Metadata 等元数据

注意：LangSmith 中的 Cost 计算仅供参考，实际账单请以模型供应商为准。

五、LangSmith Studio 配置

LangSmith Studio 是 LangSmith 提供的免费可视化交互界面，让我们能够实时观察 Agent 内部到底发生了什么，并支持实时调试。

整体分为四步：

5.1 编写 agent.py

from deepagents import create_deep_agent

internet_subagent = {
    "name": "internet-agent",
    "description": "Utilise online tools to search for information on the internet",
    "system_prompt": "You are a great Internet searcher",
    "tools": [internet_search],
    "model": model,
}

agent_test = create_deep_agent(
    model=model,
    subagents=[internet_subagent]
)

5.2 编写 langgraph.json

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./agent.py:agent_test"
  },
  "env": ".env"
}

最终的项目结构：

project/
├── .env              # 环境变量（API Key 等）
├── agent.py          # Agent 定义文件
└── langgraph.json    # LangGraph CLI 配置

5.3 启动开发服务器

langgraph dev

启动成功后会输出：

API: http://127.0.0.1:2024
Studio UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
API Docs: http://127.0.0.1:2024/docs

注意：langgraph dev 是内存服务器，仅适合本地开发测试；生产环境请使用 LangSmith Deployment。

六、LangSmith Studio 使用详解

启动 langgraph dev 后，可以通过浏览器打开 Studio UI 与本地 Agent 实时交互。

6.1 界面分区

6.2 三大特性

特性	说明
热重载	修改 `agent.py` 后无需手动重启，变更自动生效
实时编辑	在 Studio 中即可调整输入，立即看到 Agent 反应
多线程隔离	不同 Thread 独立保存上下文，互不干扰，方便多场景对比

6.3 一次完整的调试流程

七、总结与学习路径

LangSmith 的学习曲线其实非常平缓，按照下面的顺序走一遍就能上手：

一图回顾四大核心能力

能力	解决的问题
Observability	Agent 是黑盒？—— 用 Trace 看清每一步
Evaluation	改完提示词到底有没有用？—— 用数据集量化对比
Prompt Engineering	提示词乱成一团？—— 用版本控制和协作管理
Deployment	本地跑得起来怎么上线？—— 一键部署到 LangSmith 基础设施

后续可深入方向

Evaluation：在生产 / 离线数据集上批量评分 Agent 输出
Prompt Hub：使用 LangSmith Hub 进行提示词的版本管理与团队协作
Deployment：将本地 Agent 一键部署为可扩展的生产服务

当我们把 Agent 从黑盒变成白盒，调试效率就不再是瓶颈，剩下的就是专注业务本身了。

如果本文对你有帮助，欢迎点赞、收藏、转发 🙌

Ai, LangChain

LangChain Ai Python

许可协议: CC BY 4.0