Local dev testing

---
title: 本地开发与测试
description: 比较 langgraph dev 和 langgraph up 在 Agent Server 应用本地开发和类生产环境测试中的用途。
icon: "device-laptop"
---

本指南介绍如何在本地开发和测试 [Agent Server](/langsmith/agent-server) 应用。[LangGraph CLI](/langsmith/cli) 提供了两个用于本地开发的命令，每个命令针对工作流程的不同阶段进行了优化：

- [`langgraph dev`](#langgraph-dev)：一个轻量级的开发服务器，用于快速迭代。
- [`langgraph up`](#langgraph-up)：一个类生产环境的测试环境，用于验证。

| 功能 | `langgraph dev` | `langgraph up` |
|------|----------------|----------------|
| **需要 Docker** | 否 | 是 |
| **安装** | `pip install langgraph-cli[inmem]` | `pip install langgraph-cli` |
| **主要用途** | 快速开发与测试 | 类生产环境验证 |
| **状态持久化** | 内存中 & 序列化到本地目录 | PostgreSQL |
| **热重载** | 是（默认） | 可选（`--watch` 标志） |
| **默认端口** | `2024` | `8123` |
| **资源占用** | 轻量 | 较重（为服务器、PostgreSQL 和 Redis 构建并运行独立的 Docker 容器） |
| **IDE 调试** | 内置 [DAP](https://microsoft.github.io/debug-adapter-protocol/) 支持 | 常规容器调试 |
| **自定义认证** | 是 | 是（需要许可证密钥） |

<Tip>
完整的参考详情，请参阅 [LangGraph CLI 参考](/langsmith/cli) 页面。
</Tip>

## 开发

以下是构建应用程序时的典型工作流程：

```mermaid
flowchart LR
    A["开发<br/><code>langgraph dev</code>"] --> B["本地测试<br/><code>langgraph dev</code>"] --> C["验证<br/><code>langgraph up</code>"] --> D["部署<br/>通过 UI 或 API"]

    style A fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
    style B fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
    style C fill:#FDF3FF,stroke:#7E65AE,stroke-width:2px,color:#504B5F
    style D fill:#F6FFDB,stroke:#6E8900,stroke-width:2px,color:#2E3900

阶段	工具	目的
本地开发与测试	`langgraph dev`	使用热重载编写和迭代您的图
验证	`langgraph up`	使用完整技术栈测试类生产环境行为
部署	`langgraph deploy`	确信无疑地部署到生产环境

`langgraph dev`

langgraph dev 命令直接在您的环境中运行一个轻量级服务器，专为活动开发期间的速度和便利性设计。主要功能包括：

无需 Docker：直接在您的环境中运行。
热重载：当您更改代码时自动重新加载。
启动快速：几秒钟内准备就绪。
内置调试适配器协议支持：将您的 IDE 调试器附加到服务器，进行行级断点和调试。
本地存储：状态持久化到本地目录。

dev 服务器使用与生产环境相同的集成测试套件进行测试，以确保其在开发期间使用最少资源时的行为与生产环境一致。

开始使用 langgraph dev

开始之前，请确保您拥有：

LangSmith 的 API 密钥（免费注册）。
用于 Python 的 uv 或用于 TypeScript 的 npx。

创建 LangGraph 应用

从 new-langgraph-project-python 模板或 new-langgraph-project-js 模板创建一个新应用。该模板演示了一个单节点应用，您可以使用自己的逻辑进行扩展。

Python 服务器
Node 服务器

uvx --from langgraph-cli@latest langgraph new path/to/your/app --template new-langgraph-project-python

npx @langchain/langgraph-cli new path/to/your/app --template new-langgraph-project-js

其他模板
如果您在不指定模板的情况下使用 langgraph new，系统将显示一个交互式菜单，允许您从可用模板列表中进行选择。

安装依赖

Python 服务器
Node 服务器

cd path/to/your/app
uv sync --dev -U

cd path/to/your/app
yarn install

启动 Agent Server

Python 服务器
Node 服务器

uv run langgraph dev

npx @langchain/langgraph-cli dev

示例输出：

>    准备就绪！
>
>    - API: [http://localhost:2024](http://localhost:2024/)
>
>    - 文档: http://localhost:2024/docs
>
>    - Studio Web UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024

测试 API

Python SDK (async)
Python SDK (sync)
Javascript SDK
Rest API

安装 LangGraph Python SDK：

pip install langgraph-sdk

向助手发送消息（无线程运行）：

from langgraph_sdk import get_client
import asyncio

client = get_client(url="http://localhost:2024")

async def main():
    async for chunk in client.runs.stream(
        None,  # 无线程运行
        "agent", # 助手名称。在 langgraph.json 中定义。
        input={
        "messages": [{
            "role": "human",
            "content": "什么是 LangGraph？",
            }],
        },
    ):
        print(f"正在接收类型为 {chunk.event} 的新事件...")
        print(chunk.data)
        print("\n\n")

asyncio.run(main())

安装 LangGraph Python SDK：

pip install langgraph-sdk

向助手发送消息（无线程运行）：

from langgraph_sdk import get_sync_client

client = get_sync_client(url="http://localhost:2024")

for chunk in client.runs.stream(
    None,  # 无线程运行
    "agent", # 助手名称。在 langgraph.json 中定义。
    input={
        "messages": [{
            "role": "human",
            "content": "什么是 LangGraph？",
        }],
    },
    stream_mode="messages-tuple",
):
    print(f"正在接收类型为 {chunk.event} 的新事件...")
    print(chunk.data)
    print("\n\n")

安装 LangGraph JS SDK：

npm install @langchain/langgraph-sdk

向助手发送消息（无线程运行）：

const { Client } = await import("@langchain/langgraph-sdk");

// 仅当您在调用 langgraph dev 时更改了默认端口时才设置 apiUrl
const client = new Client({ apiUrl: "http://localhost:2024"});

const streamResponse = client.runs.stream(
    null, // 无线程运行
    "agent", // 助手 ID
    {
        input: {
            "messages": [
                { "role": "user", "content": "什么是 LangGraph？"}
            ]
        },
        streamMode: "messages-tuple",
    }
);

for await (const chunk of streamResponse) {
    console.log(`正在接收类型为 ${chunk.event} 的新事件...`);
    console.log(JSON.stringify(chunk.data));
    console.log("\n\n");
}

curl -s --request POST \
    --url "http://localhost:2024/runs/stream" \
    --header 'Content-Type: application/json' \
    --data "{
        \"assistant_id\": \"agent\",
        \"input\": {
            \"messages\": [
                {
                    \"role\": \"human\",
                    \"content\": \"什么是 LangGraph？\"
                }
            ]
        },
        \"stream_mode\": \"messages-tuple\"
    }"

使用场景

将 langgraph dev 用作您的主要开发工具，适用于：

日常功能开发：更改代码后服务器自动重新加载。无需重建容器即可立即测试——非常适合快速迭代周期。
快速原型设计和实验：几秒钟内启动服务器测试想法，无需 Docker 设置开销。
无 Docker 的环境：在 CI/CD 流水线或无法使用 Docker 的轻量级虚拟机中：
langgraph dev --no-browser
调试器附加：使用 --debug-port 将您的 IDE 调试器附加到服务器，在开发期间进行单步调试。

`langgraph up`

langgraph up 命令协调一个完整的、基于 Docker 的技术栈，该技术栈镜像了生产基础设施，有助于在生产之前发现部署问题。主要功能包括：

验证构建和依赖：测试您的构建过程和依赖。
隔离的网络：逼真的容器网络。
生产验证：验证部署就绪情况。

开始使用 langgraph up

# Ensure Docker is running
docker ps

# Start production-like stack
langgraph up

您的服务器将在 http://localhost:8123 启动，并具有完整的持久化存储。

使用场景

将 langgraph up 用于验证和生产就绪性测试：

部署前验证：在部署到生产环境之前，您可以使用全新构建运行最终检查，确保所有依赖项都已正确指定。
langgraph up --recreate
这可以捕获容器中依赖解析相关的问题以及任何其他构建过程问题。
主要功能验证：实现重大更改后，定期使用完整的生产技术栈进行测试，确保一切在容器化环境中正常工作。
Docker 故障排除：调试仅在生产环境中出现的容器特定问题、网络问题或环境变量配置时。

部署前检查清单

在部署应用程序之前，请使用 langgraph up 验证以下内容：

所有依赖项在容器中正确安装。
应用程序启动无错误。
图执行成功。
所有环境变量工作正常。
身份验证/授权按预期工作。

依赖配置

langgraph dev 和 langgraph up 都从您的配置文件读取应用程序的依赖项，但它们运行在不同的环境中：

langgraph dev 直接在您的本地环境（Python 或 Node.js）中运行代码，不使用 Docker。
langgraph up 构建一个 Docker 容器，并在该隔离的容器内运行您的代码。

正确配置依赖项可确保两个命令都能正常工作，并且您在本地测试的内容与部署到生产环境的内容相匹配。

`langgraph.json` 文件

dependencies 字段告诉 CLI 在哪里找到您的应用程序代码。dependencies 字段可以指向：

包含包配置的目录（包含 pyproject.toml、setup.py、requirements.txt 或 package.json）
特定子目录："dependencies": ["./my_agent"]
特定包："dependencies": ["my-package==1.0.0"] (Python) 或 "dependencies": ["my-package@1.0.0"] (JavaScript)

Python
JavaScript

{
  "dependencies": ["."],
  "graphs": {
    "my_agent": "./my_agent/agent.py:graph"
  },
  "env": "./.env"
}

{
  "dependencies": ["."],
  "graphs": {
    "my_agent": "./my_agent/agent.js:graph"
  },
  "env": "./.env"
}

包依赖文件

这些文件定义了您的应用程序需要哪些包：

Python
JavaScript

pyproject.toml 示例：

[project]
name = "my-agent"
version = "0.1.0"
dependencies = [
    "langchain-openai",
    "langchain-anthropic",
    "langgraph",
]

requirements.txt 示例：

langchain-openai
langchain-anthropic
langgraph

package.json 示例：

{
  "name": "my-agent",
  "version": "1.0.0",
  "dependencies": {
    "@langchain/openai": "^0.3.0",
    "@langchain/anthropic": "^0.3.0",
    "@langchain/langgraph": "^0.2.0"
  }
}

依赖解析过程

当您运行 langgraph up 时，CLI 按照以下步骤安装应用程序的依赖项：

langgraph.json 告诉 CLI 在哪里查找您的应用程序代码。dependencies: ["."] 字段指向当前目录。
查找包配置：CLI 在该目录中查找包配置文件（pyproject.toml、requirements.txt 或 package.json）。
读取依赖列表：CLI 从配置文件中读取包列表。
安装包：CLI 使用适合您语言的包管理器（Python 的 uv 或 pip，JavaScript 的 npm）安装所有包。

这种两文件方法分离了关注点：langgraph.json 处理应用程序结构和位置，而包配置文件处理特定于语言的包依赖。有关安装程序的更多信息，请参阅 CLI 配置文件。

故障排除

如果在依赖安装方面遇到问题，请尝试切换到 pip：

{
  "dependencies": ["."],
  "pip_installer": "pip"
}

然后重新构建：

langgraph up --recreate

调试本地 Docker 设置

即使 langgraph up 在您的本地机器上失败，生产部署也可能成功。这是因为生产环境使用托管基础设施，而 langgraph up 在您的计算机上本地运行完整技术栈。以下是不影响生产环境的常见本地环境问题。

Docker 配置问题

langgraph up 需要本地安装 Docker：

# Check if Docker is running
docker ps

云部署不使用您的本地 Docker。 解决方案：安装 Docker，或使用 langgraph dev 进行本地测试。

端口冲突

langgraph up 使用的端口 8123、5432 和 6379 可能已被占用：

# Check for conflicts
lsof -i :8123  # API server
lsof -i :5432  # PostgreSQL
lsof -i :6379  # Redis

解决方案：停止冲突的服务或使用 --port 标志。

资源限制

langgraph up 需要更多内存和磁盘空间用于：

PostgreSQL 容器
Redis 容器
API 服务器容器

解决方案：释放资源或使用 langgraph dev。

网络配置

VPN 连接、防火墙规则或企业代理设置可能会影响本地 Docker 网络。 解决方案：使用 langgraph dev 进行测试，或暂时禁用 VPN/防火墙以隔离问题。

后续步骤

现在您已经在本地运行了一个 LangGraph 应用程序，可以准备部署了： 为 LangSmith 选择托管选项：

云端：设置最快，完全托管（推荐）。
自托管：在您的基础设施中拥有完全控制权。

更多详情，请参阅平台设置比较。 然后部署您的应用：

部署到云端快速入门：快速设置指南。
完整的云端设置指南：全面的部署文档。

探索功能：

Studio：使用 Studio UI 可视化、交互和调试您的应用程序。尝试 Studio 快速入门。
API 参考：LangSmith 部署 API、Python SDK、JS/TS SDK

Deployment components

Develop & test

Frameworks and platforms

Reference

推荐工作流程

`langgraph dev`

使用场景

`langgraph up`

使用场景

部署前检查清单

依赖配置

`langgraph.json` 文件

包依赖文件

依赖解析过程

故障排除

调试本地 Docker 设置

Docker 配置问题

端口冲突

资源限制

网络配置

后续步骤

相关资源

​推荐工作流程

​langgraph dev

​使用场景

​langgraph up

​使用场景

​部署前检查清单

​依赖配置

​langgraph.json 文件

​包依赖文件

​依赖解析过程

​故障排除

​调试本地 Docker 设置

​Docker 配置问题

​端口冲突

​资源限制

​网络配置

​后续步骤

​相关资源

推荐工作流程

`langgraph dev`

使用场景

`langgraph up`

使用场景

部署前检查清单

依赖配置

`langgraph.json` 文件

包依赖文件

依赖解析过程

故障排除

调试本地 Docker 设置

Docker 配置问题

端口冲突

资源限制

网络配置

后续步骤

相关资源