LangSmith Studio

在本地使用 LangChain 构建智能体时，可视化智能体内部发生的事情、实时与之交互，并在问题出现时进行调试会很有帮助。LangSmith Studio 是一个免费的视觉界面，让你可以在本地机器上开发和测试 LangChain 智能体。

Studio 会连接到你在本地运行的智能体，向你展示智能体执行的每一步：发送给模型的提示词、工具调用及其结果，以及最终输出。你可以测试不同的输入、检查中间状态，并在无需额外代码或部署的情况下迭代智能体的行为。

本页介绍如何为你的本地 LangChain 智能体设置 Studio。

前置条件

在开始之前，请确保你具备以下条件：

• 一个 LangSmith 账户：免费注册或登录 smith.langchain.com。
• 一个 LangSmith API 密钥：按照创建 API 密钥指南操作。
• 如果你不希望将数据追踪到 LangSmith，请在你的应用 .env 文件中设置 LANGSMITH_TRACING=false。禁用追踪后，不会有任何数据离开你的本地服务器。

设置本地 Agent Server

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.5",
    tools=[send_email],
    system_prompt="You are an email assistant. Always use the send_email tool.",
)

3. 环境变量

Studio 需要一个 LangSmith API 密钥来连接你的本地智能体。请在项目根目录创建一个 .env 文件，并添加来自 LangSmith 的 API 密钥。

WARNING

确保你的 .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 键所期望的内容。

INFO

关于配置文件的 JSON 对象中各个键的详细说明，请参阅 LangGraph 配置文件参考。

此时，项目结构将如下所示：

my-app/
├── src
│   └── agent.py
├── .env
└── langgraph.json

5. 安装依赖

从根目录安装项目依赖：

pip

pip install langchain langchain-openai

uv

uv add langchain langchain-openai

6. 在 Studio 中查看你的智能体

启动开发服务器，将你的智能体连接到 Studio：

langgraph dev

WARNING

Safari 会阻止与 Studio 的 localhost 连接。要解决此问题，请在上述命令中加入 --tunnel 运行，以通过安全隧道访问 Studio。你需要点击 Studio UI 中的 Connect to a local server，手动将隧道 URL 添加到允许的来源。步骤请参见故障排除指南。

服务器运行后，你的智能体既可以通过 API（http://127.0.0.1:2024）访问，也可以通过 Studio UI（https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024）访问：

将 Studio 连接到你的本地智能体后，你可以快速迭代智能体的行为。运行测试输入，在 LangSmith 中查看完整执行追踪，包括提示词、工具参数、返回值以及 token/延迟指标。当出现问题时，Studio 会连同周边状态一起捕获异常，帮助你了解发生了什么。

开发服务器支持热重载——在代码中修改提示词或工具签名后，Studio 会立即反映这些更改。你可以从任意步骤重新运行对话线程，无需从头开始即可测试你的更改。此工作流既能胜任简单的单工具智能体，也能扩展到复杂的多节点图。

有关如何运行 Studio 的更多信息，请参阅 LangSmith 文档中的以下指南：

• 运行应用
• 管理助手
• 管理线程
• 迭代提示词
• 调试 LangSmith 追踪
• 将节点添加到数据集

视频指南

---