本地开发与测试 - 以编程方式使用文档

本指南介绍如何开发和测试 Agent Server 应用程序的本地开发。 LangGraph CLI 提供了两个本地开发命令，每个命令都针对工作流程的不同阶段进行了优化：

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

功能	`langgraph dev`	`langgraph up`
需要 Docker	否	是
安装	`pip install langgraph-cli[inmem]`	`pip install langgraph-cli`
主要用例	快速开发与测试	类生产环境验证
状态持久化	内存中保存并持久化到本地目录	PostgreSQL
热重载	是（默认）	可选（`--watch` 标志）
默认端口	`2024`	`8123`
资源使用	轻量级	较重（构建并运行独立的 Docker 容器来运行服务器、PostgreSQL 和 Redis）
IDE 调试	内置 DAP 支持	常规容器调试
自定义身份验证	是	是（需要许可证密钥）

开发

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

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`	自信地部署到生产环境

`langgraph dev`

这 langgraph dev 命令直接在您的环境中运行一个轻量级服务器，专为快速开发和便捷使用而设计。主要功能包括：

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

Get started with langgraph dev

在开始之前，请确保您已具备： - 一个 LangSmith 的 API 密钥（免费注册）。 - uv 用于 Python 或 npx 用于 TypeScript。

Create a LangGraph app

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

Python server

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

Node server

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

Install dependencies

Python server

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

Node server

    cd path/to/your/app
    yarn install

Launch Agent Server

Python server

    uv run langgraph dev

Node server

    npx @langchain/langgraph-cli dev

示例输出：

>    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

Python SDK (async)

1. 安装 LangGraph Python SDK：

      pip install langgraph-sdk

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

      from langgraph_sdk import get_client


      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())

Python SDK (sync)

1. 安装 LangGraph Python SDK：

      pip install langgraph-sdk

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

      from langgraph_sdk import get_sync_client

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

      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?",
              }],
          },
          stream_mode="messages-tuple",
      ):
          print(f"Receiving new event of type: {chunk.event}...")
          print(chunk.data)
          print("\n\n")

Javascript SDK

1. 安装 LangGraph JS SDK：

      npm install @langchain/langgraph-sdk

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

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

      // only set the apiUrl if you changed the default port when calling langgraph dev
      const client = new Client({ apiUrl: "http://localhost:2024"});

      const streamResponse = client.runs.stream(
          null, // Threadless run
          "agent", // Assistant ID
          {
              input: {
                  "messages": [
                      { "role": "user", "content": "What is LangGraph?"}
                  ]
              },
              streamMode: "messages-tuple",
          }
      );

      for await (const chunk of streamResponse) {
          console.log(`Receiving new event of type: ${chunk.event}...`);
          console.log(JSON.stringify(chunk.data));
          console.log("\n\n");
      }

Rest API

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

使用场景

使用 langgraph dev 作为您的主要开发工具，用于：

- **日常功能开发**：更改代码后服务器会自动重载。立即测试，无需重建容器——非常适合快速迭代周期。 - **快速原型设计和实验**：几秒内启动服务器以测试想法，无需 Docker 设置的开销。 - **没有 Docker 的环境**: In CI/CD pipelines or lightweight VMs where Docker isn't available:

    langgraph dev --no-browser

附加调试器：使用 --debug-port 将 IDE 调试器附加以进行开发期间的逐行调试。

`langgraph up`

此 langgraph up 命令编排一个完整的基于 Docker 的技术栈，复制生产基础设施，帮助在生产前发现部署问题。主要功能包括：

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

Get started with 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:

- 所有依赖项在容器中正确安装。
- 应用程序启动无错误。
- 图形执行成功。
- 所有环境变量正常工作。
- Authentication/authorization 按预期工作。

依赖项配置

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

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

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

`langgraph.json` 文件

dependencies 字段告诉 CLI **** 在哪里找到您的应用程序代码。 dependencies 字段可以指向： - **包含包配置的目录** （包含 pyproject.toml, setup.py, requirements.txt, or package.json) - **一个特定子目录**: "dependencies": ["./my_agent"] - **一个特定包**: "dependencies": ["my-package==1.0.0"] （Python）或 "dependencies": ["my-package@1.0.0"] （JavaScript）

Python

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

JavaScript

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

包依赖文件

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

Python

pyproject.toml 示例：

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

requirements.txt 示例：

langchain-openai
langchain-anthropic
langgraph

JavaScript

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, or package.json).
**读取依赖列表**：CLI 从配置文件中读取包列表。
**安装包**：CLI 使用适合您语言的包管理器安装所有包（uv or pip 用于 Python， npm 用于 JavaScript）。

这种双文件方法分离了关注点： 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 flag.

资源限制

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

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

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

网络配置

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

解决方案：使用以下方式测试 langgraph dev or temporarily disable VPN/firewall to isolate the issue.

后续步骤

现在您已经在本地运行了 LangGraph 应用，可以进行部署了：

为 LangSmith 选择托管选项： - **云端**：设置最快，完全托管（推荐）。 - **Self-hosted**：在您的基础设施中完全控制。

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

然后部署您的应用： - 部署到云端快速入门：快速设置指南。 - 完整云端设置指南：综合部署文档。

探索功能： - **Studio**：使用 Studio UI 可视化、交互和调试您的应用。请尝试 Studio 快速入门. - **API 参考**: LangSmith 部署 API, Python SDK, JS/TS SDK

开发

推荐工作流程

`langgraph dev`

Get started with langgraph dev

Create a LangGraph app

Python server

Node server

Install dependencies

Python server

Node server

Launch Agent Server

Python server

Node server

Test the API

Python SDK (async)

Python SDK (sync)

Javascript SDK

Rest API

使用场景

`langgraph up`

Get started with langgraph up

使用场景

部署前检查清单

依赖项配置

`langgraph.json` 文件

Python

JavaScript

包依赖文件

Python

JavaScript

依赖解析过程

故障排除

调试本地 Docker 设置

Docker 配置问题

端口冲突

资源限制

网络配置

后续步骤

相关资源

开发

推荐工作流程

langgraph dev

Get started with langgraph dev

Create a LangGraph app

Python server

Node server

Install dependencies

Python server

Node server

Launch Agent Server

Python server

Node server

Test the API

Python SDK (async)

Python SDK (sync)

Javascript SDK

Rest API

使用场景

langgraph up

Get started with langgraph up

使用场景

部署前检查清单

依赖项配置

langgraph.json 文件

Python

JavaScript

包依赖文件

Python

JavaScript

依赖解析过程

故障排除

调试本地 Docker 设置

Docker 配置问题

端口冲突

资源限制

网络配置

后续步骤

相关资源

`langgraph dev`

`langgraph up`

`langgraph.json` 文件