在本地使用 LangChain 构建代理时，可视化代理内部发生的事情、实时交互并在问题发生时进行调试很有帮助。LangSmith Studio 是一个免费的视觉界面，用于从您的本地机器开发和测试 LangChain 代理。 Studio 连接到您本地运行的代理，向您显示代理采取的每个步骤：发送到模型的提示、工具调用及其结果以及最终输出。您可以测试不同的输入、检查中间状态，并迭代代理的行为，而无需额外的代码或部署。 本页面介绍如何使用您的本地 LangChain 代理设置 Studio。

​
前置条件

在开始之前，请确保您具备以下条件：
  • LangSmith 账户：在 smith.langchain.com 注册（免费）或登录。
  • LangSmith API 密钥：按照创建 API 密钥指南操作。
  • 如果您不希望数据被跟踪到 LangSmith，请在应用程序的 .env 文件中设置 LANGSMITH_TRACING=false。禁用跟踪后，不会从本地服务器传出任何数据。

​
设置本地代理服务器

​
1. 安装 LangGraph CLI

LangGraph CLI 提供一个本地开发服务器（也称为代理服务器），将您的代理连接到 Studio。 
# Python >= 3.11 is required.
pip install --upgrade "langgraph-cli[inmem]"

​
2. 准备您的代理

如果您已经有 LangChain 代理，可以直接使用。此示例使用一个简单的邮件代理：
agent.py
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.2",
    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）。
.env
LANGSMITH_API_KEY=lsv2...

​
4. 创建 LangGraph 配置文件

LangGraph CLI 使用配置文件来定位您的代理并管理依赖项。在应用程序目录中创建 langgraph.json 文件：
langgraph.json
{
  "dependencies": ["."],
  "graphs": {
    "agent": "./src/agent.py:agent"
  },
  "env": ".env"
}
create_agent 函数自动返回编译的 LangGraph 图，这正是配置文件中 graphs 键所期望的。
有关配置文件 JSON 对象中每个键的详细说明，请参阅 LangGraph 配置文件参考。
此时，项目结构将如下所示： 
my-app/
├── src
│   └── agent.py
├── .env
└── langgraph.json

​
5. 安装依赖项

从根目录安装项目依赖项： 
pip install langchain langchain-openai

​
6. 在 Studio 中查看您的代理

启动开发服务器以将您的代理连接到 Studio： 
langgraph dev
Safari 阻止对 Studio 的 localhost 连接。要解决此问题，请使用 --tunnel 运行上述命令以通过安全隧道访问 Studio。
服务器运行后，您的代理既可以通过 http://127.0.0.1:2024 的 API 访问，也可以通过 Studio UI 在 https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024 访问：
Studio UI 中的代理视图
Studio 连接到您的本地代理后，您可以快速迭代代理的行为。运行测试输入、检查完整的执行跟踪（包括提示、工具参数、返回值和令牌/延迟指标）。当出现问题时，Studio 会捕获带有周围状态的异常，以帮助您了解发生了什么。 开发服务器支持热重载——在代码中更改提示或工具签名，Studio 会立即反映这些更改。从任何步骤重新运行对话线程以测试您的更改，而无需重新开始。此工作流程从简单的单工具代理扩展到复杂的多节点图。 有关如何运行 Studio 的更多信息，请参阅 LangSmith 文档中的以下指南：

​
视频指南

有关已部署代理的更多信息，请参阅部署。
在 GitHub 上编辑此页面 或 提交问题。
通过 MCP 将这些文档连接到 Claude、VSCode 等，获取实时答案。