6.1 LangSmith Studio
LangSmith Studio 是一个专业的 Agent IDE，用于可视化、交互和调试基于 LangGraph 构建的代理系统。
概述
LangSmith Studio 是 LangSmith 平台的核心开发工具，它提供了一个免费的可视化界面，让开发者能够从本地机器开发和测试 LangChain 代理。Studio 能够显示代理执行的每一步，包括模型提示、工具调用结果和最终输出。
核心功能
| 功能 | 说明 |
|---|---|
| 图架构可视化 | 查看代理的完整执行流程和节点关系 |
| 实时交互 | 在不部署的情况下测试不同输入 |
| 状态检查 | 检查中间状态和执行细节 |
| 热重载 | 代码更改自动反映在界面中 |
| 时间旅行调试 | 从任何步骤重新运行对话 |
| 助手管理 | 创建和管理多个代理配置 |
| 线程管理 | 管理对话历史和上下文 |
| 长期记忆管理 | 持久化代理的学习和记忆 |
操作模式
Studio 提供两种操作模式，适用于不同场景：
Graph Mode（图模式）
提供完整的功能访问，包含详细的执行可见性：
┌─────────────────────────────────────────────────────┐
│ Graph Mode │
├─────────────────────────────────────────────────────┤
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Start │───▶│ Node │───▶│ End │ │
│ └─────────┘ └────┬────┘ └─────────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ Tools │ │
│ └──────────┘ │
│ │
│ [Traversed Nodes] [States] [LangSmith Traces] │
└─────────────────────────────────────────────────────┘特点：
- 可视化展示图中所有遍历的节点
- 显示每个步骤的中间状态
- 集成 LangSmith 进行数据集管理和 Playground 访问
Chat Mode（聊天模式）
简化的界面，专为聊天类代理设计：
┌─────────────────────────────────────────────────────┐
│ Chat Mode │
├─────────────────────────────────────────────────────┤
│ │
│ User: 你好，帮我搜索一下天气 │
│ ───────────────────────────────── │
│ Assistant: 正在为您搜索天气信息... │
│ [Tool: weather_search] │
│ Assistant: 今天北京晴，温度 25°C │
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ 输入消息... [Send]│ │
│ └──────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────┘特点：
- 适用于业务用户和行为测试
- 支持状态包含
MessagesState的图 - 界面简洁，专注于对话交互
环境准备
前置要求
- LangSmith 账户：免费注册 smith.langchain.com
- Python 3.11+
- API 密钥：从 LangSmith 获取
安装 CLI 工具
bash
pip install --upgrade "langgraph-cli[inmem]"配置步骤
1. 创建环境变量文件
在项目根目录创建 .env 文件：
bash
# .env
LANGSMITH_API_KEY=lsv2_your_api_key_here
# 可选：禁用追踪（保持数据本地）
# LANGSMITH_TRACING=false2. 创建 LangGraph 配置文件
创建 langgraph.json：
json
{
"dependencies": ["."],
"graphs": {
"agent": "./src/agent.py:agent"
},
"env": ".env"
}配置说明：
| 字段 | 说明 |
|---|---|
dependencies | Python 依赖路径 |
graphs | 图名称到模块路径的映射 |
env | 环境变量文件路径 |
3. 创建代理代码
python
# src/agent.py
from langgraph.graph import StateGraph, MessagesState, START, END
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
# 定义工具
@tool
def search(query: str) -> str:
"""搜索信息"""
return f"搜索结果: {query} 的相关信息..."
@tool
def calculator(expression: str) -> str:
"""计算数学表达式"""
try:
result = eval(expression)
return f"计算结果: {result}"
except Exception as e:
return f"计算错误: {e}"
# 创建模型
model = ChatOpenAI(model="gpt-4o").bind_tools([search, calculator])
# 定义节点
def agent_node(state: MessagesState):
response = model.invoke(state["messages"])
return {"messages": [response]}
def tool_node(state: MessagesState):
# 工具执行逻辑
last_message = state["messages"][-1]
tool_calls = last_message.tool_calls
results = []
for call in tool_calls:
if call["name"] == "search":
result = search.invoke(call["args"])
elif call["name"] == "calculator":
result = calculator.invoke(call["args"])
results.append({"role": "tool", "content": result, "tool_call_id": call["id"]})
return {"messages": results}
# 条件路由
def should_continue(state: MessagesState):
last_message = state["messages"][-1]
if hasattr(last_message, "tool_calls") and last_message.tool_calls:
return "tools"
return "end"
# 构建图
graph = StateGraph(MessagesState)
graph.add_node("agent", agent_node)
graph.add_node("tools", tool_node)
graph.add_edge(START, "agent")
graph.add_conditional_edges("agent", should_continue, {"tools": "tools", "end": END})
graph.add_edge("tools", "agent")
# 编译导出
agent = graph.compile()启动开发服务器
基本启动
bash
langgraph dev服务器将在 http://127.0.0.1:2024 运行。
访问 Studio
打开浏览器访问：
https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024开发模式选项
bash
# 使用隧道（解决 Safari 限制）
langgraph dev --tunnel
# 附加调试器
langgraph dev --debug-port 5678
# 指定配置文件
langgraph dev --config ./my-config.json使用 Studio 调试
执行可视化
Studio 会显示代理的完整执行流程：
┌────────────────────────────────────────────────────────────┐
│ 执行追踪 │
├────────────────────────────────────────────────────────────┤
│ │
│ [1] START │
│ └─▶ 用户输入: "帮我搜索并计算 2+2" │
│ │
│ [2] AGENT │
│ └─▶ 模型思考: 需要先搜索，再计算 │
│ └─▶ 工具调用: search("2+2 相关信息") │
│ │
│ [3] TOOLS │
│ └─▶ 执行: search │
│ └─▶ 返回: "搜索结果: ..." │
│ │
│ [4] AGENT │
│ └─▶ 工具调用: calculator("2+2") │
│ │
│ [5] TOOLS │
│ └─▶ 执行: calculator │
│ └─▶ 返回: "计算结果: 4" │
│ │
│ [6] AGENT │
│ └─▶ 最终回复: "搜索结果为...，2+2=4" │
│ │
│ [7] END │
│ │
└────────────────────────────────────────────────────────────┘状态检查
点击任意节点可查看该步骤的详细状态：
python
# 示例：节点状态快照
{
"messages": [
{"role": "user", "content": "帮我搜索并计算 2+2"},
{"role": "assistant", "tool_calls": [...]},
{"role": "tool", "content": "搜索结果: ..."},
],
"intermediate_steps": [...],
"agent_scratchpad": "..."
}时间旅行调试
从任意步骤重新开始执行：
- 选择要回退的节点
- 点击 "Replay from here"
- 修改输入或状态
- 观察新的执行路径
隐私设置
如果不希望数据上传到 LangSmith，可以禁用追踪：
bash
# .env
LANGSMITH_TRACING=false这样所有数据将保持在本地，不会发送到云端。
部署模式连接
连接到云端部署
对于已部署的代理，通过 LangSmith UI 的 Deployments 部分访问 Studio：
- 登录 LangSmith
- 导航到 Deployments
- 选择您的部署
- 点击 "Open in Studio"
连接到本地服务器
- 访问
https://smith.langchain.com/studio - 输入本地服务器地址：
http://localhost:2024 - 开始调试
最佳实践
开发工作流
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 编写代码 │────▶│ Studio 测试 │────▶│ 修复问题 │
└─────────────┘ └─────────────┘ └─────────────┘
▲ │
└────────────────────────────────────────┘
迭代循环建议
| 场景 | 建议 |
|---|---|
| 开发阶段 | 使用 langgraph dev 本地开发 |
| 调试复杂流程 | 使用 Graph Mode 查看完整执行路径 |
| 用户测试 | 使用 Chat Mode 简化界面 |
| 敏感数据 | 设置 LANGSMITH_TRACING=false |
| Safari 浏览器 | 使用 --tunnel 选项 |
常见问题
Q: Studio 无法连接到本地服务器？
A: 检查以下几点：
- 确保
langgraph dev正在运行 - 检查端口 2024 是否被占用
- Safari 用户需要使用
--tunnel选项
Q: 看不到执行追踪？
A: 确保 LANGSMITH_TRACING 未设置为 false，并且 API Key 正确配置。
Q: 如何调试特定步骤？
A: 使用时间旅行功能，从任意节点重新执行，观察状态变化。
下一节：6.2 Test