BytesRouter

主题

LangSmith 文档版本 跟随上游 源快照 7289bbb3 更新于 2026-10-18

本地开发与测试

比较 langgraph dev 与 langgraph up，用于 Agent Server 应用的本地开发和类生产测试。

本指南介绍如何在本地开发和测试 Agent Server 应用。LangGraph CLI 提供两个用于本地开发的命令，各为你工作流的不同阶段而优化：

  • langgraph dev：一个用于快速迭代的轻量开发服务器。
  • langgraph up：一个用于验证的类生产测试环境。
特性langgraph devlanggraph up
需要 Docker否是
安装pip install langgraph-cli[inmem]pip install langgraph-cli
主要用例快速开发与测试类生产验证
状态持久化内存中并 pickle 到本地目录PostgreSQL
热重载是（默认）可选（--watch 标志）
默认端口20248123
资源占用轻量较重（为服务器、PostgreSQL 和 Redis 构建并运行单独的 docker 容器）
IDE 调试内置 DAP 支持常规容器调试
自定义身份验证是是（带许可密钥）

TIP

完整的参考详情，参阅 LangGraph CLI 参考 页面。

开发

这是构建应用时的典型工作流：

flowchart LR
    A["Develop<br/><code>langgraph dev</code>"] --> B["Test Locally<br/><code>langgraph dev</code>"] --> C["Validate<br/><code>langgraph up</code>"] --> D["Deploy<br/>via UI or 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有信心地部署到生产

推荐工作流

  1. 日常开发：用 langgraph dev 快速迭代。
  2. 定期验证：用 langgraph up 测试重大变更。
  3. 部署前检查：运行 langgraph up --recreate 做一次全新构建。
  4. 部署：通过 LangSmith UI 或 控制平面 API 推送到生产。

langgraph dev

langgraph dev 命令在你的环境中直接运行一个轻量服务器，专为活跃开发期间的速度和便利设计。关键特性包括：

  • 无需 Docker：在你的环境中直接运行。
  • 热重载：当你更改代码时自动重载。
  • 快速启动：几秒就绪。
  • 内置 Debug Adapter Protocol 支持：把你的 IDE 调试器附加到服务器以做行级断点和调试。
  • 本地存储：状态持久化到本地目录。

NOTE

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

Get started with langgraph dev

Before you begin, ensure you have:

  • An API key for LangSmith (free to sign up).
  • uv for Python or npx for TypeScript.

Create a LangGraph app

Create a new app from the new-langgraph-project-python template or new-langgraph-project-js template. This template demonstrates a single-node application you can extend with your own logic.

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

TIP

Additional templates
If you use langgraph new without specifying a template, you will be presented with an interactive menu that will allow you to choose from a list of available templates.

Install dependencies

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

Launch Agent Server

shell
uv run langgraph dev

Sample output:

>    Ready!
>
>    - API: [http://localhost:2024](http://localhost:2024/)
>
>    - Docs: http://localhost:2024/docs
>
>    - Studio Web UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024

Test the API

  1. Install the LangGraph Python SDK:
shell
pip install langgraph-sdk
  1. Send a message to the assistant (threadless run):
python
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,  # Threadless run
        "agent", # Name of assistant. Defined in langgraph.json.
        input={
        "messages": [{
            "role": "human",
            "content": "What is LangGraph?",
            }],
        },
    ):
        print(f"Receiving new event of type: {chunk.event}...")
        print(chunk.data)
        print("\n\n")

asyncio.run(main())

使用场景

把 langgraph dev 用作你的主要开发工具来：

  • 日常功能开发：更改你的代码，服务器自动重载。无需重建容器就能立即测试——非常适合快速迭代循环。

  • 快速原型与实验：几秒内启动一个服务器来测试想法，没有 Docker 设置开销。

  • 没有 Docker 的环境：在 Docker 不可用的 CI/CD 流水线或轻量 VM 中：

    bash
    langgraph dev --no-browser

  • 调试器附加：用 --debug-port 把你的 IDE 调试器附加上，以在开发期间做单步调试。

langgraph up

langgraph up 命令编排一个完整的、镜像生产基础设施的 Docker 栈，帮助在生产之前捕捉部署问题。关键特性包括：

  • 验证构建与依赖：测试你的构建过程和依赖。
  • 隔离网络：逼真的容器网络。
  • 生产验证：验证部署就绪度。
开始使用 langgraph up
bash
# Ensure Docker is running
docker ps

# Start production-like stack
langgraph up

你的服务器在 http://localhost:8123 启动，带完整的持久存储。

使用场景

用 langgraph up 做验证和生产就绪测试：

  • 部署前验证：在部署到生产之前，你可以用一次全新构建做最后一道检查，以确保你的依赖都正确指定。

    bash
    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）
json
{
  "dependencies": ["."],
  "graphs": {
    "my_agent": "./my_agent/agent.py:graph"
  },
  "env": "./.env"
}

包依赖文件

这些文件定义你的应用需要哪些包：

pyproject.toml example:

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

requirements.txt example:

langchain-openai
langchain-anthropic
langgraph

依赖解析过程

当你运行 langgraph up 时，CLI 遵循以下步骤来安装你应用的依赖：

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

这种双文件方法分离了关注点：langgraph.json 处理应用结构和位置，而包配置文件处理语言专属的包依赖。

有关安装器的更多信息，参阅 CLI 配置文件。

故障排查

如果你在依赖安装上遇到问题，试着切换到 pip：

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

然后重新构建：

bash
langgraph up --recreate

调试你的本地 Docker 设置

生产部署可能在 langgraph up 于你本地机器失败时仍然成功。这是因为生产使用托管基础设施，而 langgraph up 在你的计算机上本地运行整个栈。

以下是不影响生产的常见本地环境问题。

Docker 配置问题

langgraph up 在本地需要 Docker：

bash
# Check if Docker is running
docker ps

云部署不使用你的本地 Docker。

解决方案：安装 Docker，或用 langgraph dev 做本地测试。

端口冲突

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

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

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

资源约束

langgraph up 需要更多 RAM 和磁盘用于：

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

解决方案：腾出资源，或使用 langgraph dev。

网络配置

VPN 连接、防火墙规则或企业代理设置会影响本地 Docker 网络。

解决方案：用 langgraph dev 测试，或临时禁用 VPN/防火墙以隔离问题。

后续步骤

现在你已在本地运行了一个 LangGraph 应用，准备好部署它了：

为 LangSmith 选择一个托管选项：

  • Cloud：最快的设置，全托管（推荐）。
  • Self-hosted：在你的基础设施中完全掌控。

更多详情，参阅平台设置对比。

然后部署你的应用：

探索功能：

相关资源

友情链接

  • Agents.md面向 AI 编码助手的仓库说明文件规范
  • LangChainLangChain 是一个开放的Agent平台
  • LangSmithAgent 工程平台：可观测与评估、部署、Fleet、Engine 等
  • EmbabelEmbabel 是一个JVM平台Agent框架
  • SpringAISpringAI 是一个基于 Spring 的 AI 框架
  • MCPModel Context Protocol，连接 AI 应用与外部数据/工具的开放标准
  • LangChain4jJava 生态的 LLM 应用开发框架
  • LlamaIndex把数据接入 LLM 的框架与文档平台
  • LlamaParse智能体式 OCR 文档解析：把 PDF、扫描件变成 LLM 可用的文本与结构化数据
  • LiteParse本地优先、轻量的文档解析库，不需要 API key
  • CrewAI多智能体编排框架：以 Crew/Flow 组织自主协作的 AI Agent
  • MAFMicrosoft Agent Framework，企业级 .NET/Python 智能体框架

BytesRouter 是社区翻译站点，所有译文仅供参考，一切以官方英文原文为准。

© 2026 BytesRouter · 译文采用 CC BY 4.0 许可