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

# LangSmith Studio

在本地使用 LangChain 构建智能体时，能够可视化智能体内部的运行情况、实时与之交互并在问题发生时进行调试非常有帮助。**LangSmith Studio** 是一个免费的可视化界面，用于从本地机器开发和测试你的 LangChain 智能体。

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

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

## 前提条件

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

* **LangSmith 账户**：在 [smith.langchain.com](https://smith.langchain.com?utm_source=docs\&utm_medium=cta\&utm_campaign=langsmith-signup\&utm_content=oss-langgraph-studio) 注册（免费）或登录。
* **LangSmith API 密钥**：按照[创建 API 密钥](/langsmith/create-account-api-key)指南操作。
* 如果你不希望数据被[追踪](/langsmith/observability-concepts#traces)到 LangSmith，请在应用的 `.env` 文件中设置 `LANGSMITH_TRACING=false`。禁用追踪后，不会有数据离开你的本地服务器。

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

### 1. 安装 LangGraph CLI

[LangGraph CLI](/langsmith/cli) 提供一个本地开发服务器（也称为 [Agent Server](/langsmith/agent-server)），用于将你的智能体连接到 Studio。

```shell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 需要 Python >= 3.11。
pip install --upgrade "langgraph-cli[inmem]"
```

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

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

```python title="agent.py" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent

def send_email(to: str, subject: str, body: str):
    """发送邮件"""
    email = {
        "to": to,
        "subject": subject,
        "body": body
    }
    # ... 邮件发送逻辑

    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](https://smith.langchain.com/settings) 添加你的 API 密钥。

<Warning>
  确保你的 `.env` 文件不会被提交到版本控制系统（如 Git）。
</Warning>

```bash .env theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
LANGSMITH_API_KEY=lsv2...
```

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

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

```json title="langgraph.json" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "dependencies": ["."],
  "graphs": {
    "agent": "./src/agent.py:agent"
  },
  "env": ".env"
}
```

[`create_agent`](https://reference.langchain.com/python/langchain/agents/factory/create_agent) 函数会自动返回一个已编译的 LangGraph 图，这正是配置文件中 `graphs` 键所期望的。

<Info>
  有关配置文件 JSON 对象中每个键的详细说明，请参阅 [LangGraph 配置文件参考](/langsmith/cli#configuration-file)。
</Info>

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
my-app/
├── src
│   └── agent.py
├── .env
└── langgraph.json
```

### 5. 安装依赖

从根目录安装项目依赖：

<CodeGroup>
  ```shell pip theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  pip install langchain langchain-openai
  ```

  ```shell uv theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  uv add langchain langchain-openai
  ```
</CodeGroup>

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

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

```shell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langgraph dev
```

<Warning>
  Safari 会阻止 `localhost` 到 Studio 的连接。要解决此问题，请使用 `--tunnel` 参数运行上述命令，通过安全隧道访问 Studio。你需要在 Studio UI 中点击 **Connect to a local server** 手动添加隧道 URL 到允许的来源。详见[故障排除指南](/langsmith/troubleshooting-studio#safari-connection-issues)。
</Warning>

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

<Frame>
  <img src="https://mintcdn.com/nvd-54/KKmYhbrpyTWf5iQl/oss/images/studio_create-agent.png?fit=max&auto=format&n=KKmYhbrpyTWf5iQl&q=85&s=92f758f093f05b6162bd7b48f8b1b627" alt="Studio UI 中的智能体视图" width="2836" height="1752" data-path="oss/images/studio_create-agent.png" />
</Frame>

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

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

有关如何运行 Studio 的更多信息，请参阅 [LangSmith 文档](/langsmith/home)中的以下指南：

* [运行应用](/langsmith/use-studio#run-application)
* [管理助手](/langsmith/use-studio#manage-assistants)
* [管理线程](/langsmith/use-studio#manage-threads)
* [迭代提示词](/langsmith/observability-studio)
* [调试 LangSmith 追踪](/langsmith/observability-studio#debug-langsmith-traces)
* [将节点添加到数据集](/langsmith/observability-studio#add-node-to-dataset)

## 视频指南

<Frame>
  <iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/Mi1gSlHwZLM?si=zA47TNuTC5aH0ahd" title="Studio" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</Frame>

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档连接](/use-these-docs)到 Claude、VSCode 等工具，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/langgraph/studio.mdx)或[提交 issue](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>