在本地使用 LangChain 构建智能体时，能够可视化智能体内部正在发生的事情、实时与其交互，并在问题出现时进行调试，会非常有帮助。LangSmith Studio 是一个免费的可视化界面，用于在本地机器上开发和测试你的 LangChain 智能体。
Studio 会连接到你本地运行的智能体，向你展示智能体执行的每一步：发送给模型的提示词、工具调用及其结果，以及最终输出。你可以测试不同输入、检查中间状态，并在无需编写额外代码或部署的情况下，迭代智能体的行为。
本页介绍如何将 Studio 与你的本地 LangChain 智能体搭配使用。
前提条件
开始之前，请确保你具备以下内容：
- 一个 LangSmith 账户：在 smith.langchain.com 注册（免费）或登录。
- 一个 LangSmith API 密钥：按照 创建 API 密钥 指南操作。
- 如果你不希望将数据跟踪到 LangSmith，请在应用程序的
.env 文件中设置 LANGSMITH_TRACING=false。禁用跟踪后，不会有任何数据离开你的本地服务器。
设置本地 Agent 服务器
1. 安装 LangGraph CLI
LangGraph CLI 提供了一个本地开发服务器（也称为 Agent Server），用于将你的智能体连接到 Studio。
# Python >= 3.11 is required.
pip install --upgrade "langgraph-cli[inmem]"
2. 准备你的智能体
如果你已经有一个 LangChain 智能体，可以直接使用它。此示例使用一个简单的电子邮件智能体：
from langchain.agents import create_agent
def send_email(to: str, subject: str, body: str):
"""Send an email"""
email = {
"to": to,
"subject": subject,
"body": body
}
# ... email sending logic
return f"Email sent to {to}"
agent = create_agent(
"gpt-5.4",
tools=[send_email],
system_prompt="You are an email assistant. Always use the send_email tool.",
)
3. 环境变量
Studio 需要 LangSmith API 密钥来连接你的本地智能体。在项目根目录中创建一个 .env 文件，并添加来自 LangSmith 的 API 密钥。
请确保你的 .env 文件不会提交到 Git 等版本控制系统中。
LANGSMITH_API_KEY=lsv2...
4. 创建 LangGraph 配置文件
LangGraph CLI 使用配置文件来定位你的智能体并管理依赖项。在你的应用目录中创建一个 langgraph.json 文件：
{
"dependencies": ["."],
"graphs": {
"agent": "./src/agent.py:agent"
},
"env": ".env"
}
create_agent 函数会自动返回一个已编译的 LangGraph 图，这正是配置文件中 graphs 键所期望的内容。
此时，项目结构将如下所示：
my-app/
├── src
│ └── agent.py
├── .env
└── langgraph.json
5. 安装依赖项
从根目录安装你的项目依赖项：
pip install langchain langchain-openai
6. 在 Studio 中查看你的智能体
启动开发服务器，将你的智能体连接到 Studio：
Safari 会阻止 Studio 连接到 localhost。要解决此问题，请在运行上述命令时添加 --tunnel，通过安全隧道访问 Studio。你需要在 Studio UI 中点击 Connect to a local server，手动将隧道 URL 添加到允许的来源中。具体步骤请参阅故障排除指南。 http://127.0.0.1:2024 的 API 访问，也可以通过 https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024 的 Studio UI 访问：
当 Studio 连接到你的本地智能体后，你可以快速迭代智能体的行为。运行一个测试输入，在 LangSmith 中检查完整的执行跟踪，包括提示词、工具参数、返回值，以及 token/延迟指标。当出现问题时，Studio 会捕获异常及其周围状态，帮助你了解发生了什么。
开发服务器支持热重载——在代码中修改提示词或工具签名后，Studio 会立即反映这些变化。你可以从任意步骤重新运行会话线程，以测试你的修改，而无需从头开始。这个工作流既适用于简单的单工具智能体，也适用于复杂的多节点图。
如需了解有关如何运行 Studio 的更多信息，请参阅 LangSmith 文档中的以下指南：
视频指南
