Skip to main content
在本地使用 LangChain 构建智能体时，能够可视化智能体内部运作、实时交互并调试出现的问题非常有帮助。LangSmith Studio 是一个免费的可视化界面，用于在本地机器上开发和测试您的 LangChain 智能体。 Studio 连接到您本地运行的智能体，向您展示智能体执行的每一步：发送给模型的提示词、工具调用及其结果，以及最终输出。您可以测试不同的输入，检查中间状态，并迭代优化智能体的行为，无需额外的代码或部署。 本页介绍如何将 Studio 与您的本地 LangChain 智能体进行设置。

​
前提条件

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

​
设置本地智能体服务器

​
1. 安装 LangGraph CLI

LangGraph CLI 提供了一个本地开发服务器（也称为智能体服务器），用于将您的智能体连接到 Studio。 
npx @langchain/langgraph-cli

​
2. 准备您的智能体

如果您已经有一个 LangChain 智能体，可以直接使用它。此示例使用一个简单的电子邮件智能体：
agent.ts
import { createAgent } from "@langchain/langgraph";

function sendEmail(to: string, subject: string, body: string): string {
    // 发送电子邮件
    const email = {
        to: to,
        subject: subject,
        body: body
    };
    // ... 电子邮件发送逻辑

    return `Email sent to ${to}`;
}

const agent = createAgent({
    model: "gpt-5.4",
    tools: [sendEmail],
    systemPrompt: "You are an email assistant. Always use the sendEmail tool.",
});

export { agent };

​
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.ts:agent"
  },
  "env": ".env"
}
createAgent 函数会自动返回一个编译后的 LangGraph 图，这正是配置文件中 graphs 键所期望的格式。
有关配置文件 JSON 对象中每个键的详细说明，请参阅 LangGraph 配置文件参考。
此时，项目结构将如下所示： 
my-app/
├── src
│   └── agent.ts
├── .env
├── package.json
└── langgraph.json

​
5. 安装依赖项

yarn install

​
6. 在 Studio 中查看您的智能体

启动开发服务器，将您的智能体连接到 Studio： 
npx @langchain/langgraph-cli dev
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 UI 中的智能体视图
Studio 连接到您的本地智能体后，您可以快速迭代优化智能体的行为。运行测试输入，检查完整的执行跟踪，包括提示词、工具参数、返回值以及 LangSmith 中的 token/延迟指标。当出现问题时，Studio 会捕获异常及其周围状态，帮助您理解发生了什么。 开发服务器支持热重载——在代码中修改提示词或工具签名，Studio 会立即反映这些更改。从任何步骤重新运行对话线程以测试您的更改，无需从头开始。此工作流程可扩展到从简单的单工具智能体到复杂的多节点图。 有关如何运行 Studio 的更多信息，请参阅 LangSmith 文档中的以下指南：

​
视频指南

将这些文档通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。
在 GitHub 上编辑此页面 或 提交问题。