> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-docs-zh.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# LangSmith Studio

> 在本地使用 LangChain 构建智能体时，可视化智能体内部的操作、实时交互以及调试问题非常有帮助。LangSmith Studio 是一个免费的图形界面，用于从本地机器开发和测试您的 LangChain 智能体。

在本地使用 LangChain 构建智能体时，可视化智能体内部的操作、实时交互以及调试问题非常有帮助。**LangSmith Studio** 是一个免费的图形界面，用于从本地机器开发和测试您的 LangChain 智能体。

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

本页面描述了如何将 Studio 设置与您的本地 LangChain 智能体。

## 前置条件

开始之前，请确保您已具备以下条件：

* **一个 LangSmith 账户**：在 [smith.langchain.com](https://smith.langchain.com) 注册（免费）或登录。
* **一个 LangSmith API 密钥**：遵循 [创建 API 密钥](https://docs.langchain.com/langsmith/create-account-api-key) 指南。
* 如果您不想将数据 [追踪](https://docs.langchain.com/langsmith/observability-concepts#traces) 到 LangSmith，请在智能体的 `.env` 文件中设置 `LANGSMITH_TRACING=false`。禁用追踪后，不会有任何数据离开您的本地服务器。

## 设置本地智能体服务器

### 1. 安装 LangGraph CLI

[LangGraph CLI](https://docs.langchain.com/langsmith/cli) 提供了一个本地开发服务器（也称为 [智能体服务器](https://docs.langchain.com/langsmith/agent-server)），将您的智能体连接到 Studio。

:::python

```shell theme={null}
# Python >= 3.11 is required.
pip install --upgrade "langgraph-cli[inmem]"
```

:::

:::js

```shell theme={null}
npx @langchain/langgraph-cli
```

:::

### 2. 准备您的智能体

如果您已经有一个 LangChain 智能体，可以直接使用它。本示例使用一个简单的邮件智能体：

:::python

```python title="agent.py" theme={null}
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.",
)
```

:::

:::js

```typescript title="agent.ts" theme={null}
import { createAgent } from "@langchain/langgraph";

function sendEmail(to: string, subject: string, body: string): string {
    // Send an email
    const email = {
        to: to,
        subject: subject,
        body: body
    };
    // ... email sending logic

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

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

export { agent };
```

:::

### 3. 环境变量

> [!NOTE]
>
> 在一个 [基于智能体的工作空间](https://docs.langchain.com/langsmith/agent-registry) 中，在发送跟踪信息之前，先 [创建一个智能体](https://docs.langchain.com/langsmith/create-an-agent)。使用 [智能体寻址](https://docs.langchain.com/langsmith/log-traces-to-agent) 来选择其标识符和环境。如果集成需要 `project_name`，请使用所选环境的 [`tracer_session_name`](https://docs.langchain.com/langsmith/create-an-agent#use-an-environment-project) 作为兼容性值。

Studio 需要一个 LangSmith API 密钥来连接您的本地智能体。在项目的根目录中创建一个 `.env` 文件，并将您的 API 密钥从 [LangSmith](https://smith.langchain.com/settings) 添加到其中。

> [!WARNING]
>
> 确保您的 `.env` 文件不会被提交到版本控制，例如 Git。

```bash .env theme={null}
LANGSMITH_API_KEY=lsv2...
LANGSMITH_AGENT_ID="<your-agent-id>"
LANGSMITH_AGENT_ENVIRONMENT="production"
```

### 4. 创建 LangGraph 配置文件

LangGraph CLI 使用配置文件来定位您的智能体和管理依赖项。在应用程序目录中创建一个 `langgraph.json` 文件：

:::python

```json title="langgraph.json" theme={null}
{
  "dependencies": ["."],
  "graphs": {
    "agent": "./src/agent.py:agent"
  },
  "env": ".env"
}
```

:::

:::js

```json title="langgraph.json" theme={null}
{
  "dependencies": ["."],
  "graphs": {
    "agent": "./src/agent.ts:agent"
  },
  "env": ".env"
}
```

:::

:::python
@\[`create_agent`] 函数会自动返回一个编译后的 LangGraph 图，这是配置文件中 `graphs` 键所期望的。
:::

:::js
@\[`createAgent`] 函数会自动返回一个编译后的 LangGraph 图，这是配置文件中 `graphs` 键所期望的。
:::

> [!NOTE]
>
> 有关配置文件中 JSON 对象每个键的详细说明，请参阅 [LangGraph 配置文件参考](https://docs.langchain.com/langsmith/cli#configuration-file)。

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

:::python

```bash theme={null}
my-app/
├── src
│   └── agent.py
├── .env
└── langgraph.json
```

:::

:::js

```bash theme={null}
my-app/
├── src
│   └── agent.ts
├── .env
├── package.json
└── langgraph.json
```

:::

### 5. 安装依赖项

:::python
从根目录安装您的项目依赖项：

```shell pip theme={null}
pip install langchain langchain-openai
```

```shell uv theme={null}
uv add langchain langchain-openai
```

:::

:::js

```shell theme={null}
yarn install
```

:::

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

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

:::python

```shell theme={null}
langgraph dev
```

:::

:::js

```shell theme={null}
npx @langchain/langgraph-cli dev
```

:::

> [!WARNING]
>
> Safari 会阻止 `localhost` 连接到 Studio。为解决这个问题，请使用 `--tunnel` 运行上述命令，通过安全隧道访问 Studio。您需要手动将隧道 URL 添加到允许的来源中，方法是点击 Studio UI 中的 **连接到本地服务器**。有关步骤，请参阅 [故障排除指南](https://docs.langchain.com/langsmith/troubleshooting-studio#safari-connection-issues)。

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

![Studio UI 中的智能体视图](https://mintcdn.com/langchain-docs-zh/9aH49uhEfQVYxX8T/langchain/oss/images/studio_create-agent.png?fit=max\&auto=format\&n=9aH49uhEfQVYxX8T\&q=85\&s=88d3e852b448c428844447ee6cda8780)

将 Studio 连接到您的本地智能体后，您可以快速迭代智能体的行为。运行测试输入，在 [LangSmith](https://docs.langchain.com/langsmith/observability-studio) 中检查完整的执行追踪，包括提示词、工具参数、返回值以及 Token/延迟指标。当出现问题时，Studio 会捕获异常及其周围状态，以帮助您了解发生了什么。

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

有关如何运行 Studio 的更多信息，请参阅 [LangSmith 文档](https://docs.langchain.com/langsmith/observability) 中的以下指南：

* [运行智能体](https://docs.langchain.com/langsmith/use-studio#run-application)
* [管理智能体](https://docs.langchain.com/langsmith/use-studio#manage-assistants)
* [管理对话线程](https://docs.langchain.com/langsmith/use-studio#manage-threads)
* [迭代提示词](https://docs.langchain.com/langsmith/observability-studio)
* [调试 LangSmith 追踪](https://docs.langchain.com/langsmith/observability-studio#debug-langsmith-traces)
* [向数据集添加节点](https://docs.langchain.com/langsmith/observability-studio#add-node-to-dataset)

## 视频指南

[Studio](https://www.youtube.com/embed/Mi1gSlHwZLM?si=zA47TNuTC5aH0ahd)

***

> 官方原文：[src/oss/langgraph/studio.mdx](https://github.com/langchain-ai/docs/blob/main/src/oss/langgraph/studio.mdx) · 非官方翻译，译文由 AI 生成，以英文原文为准。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.