什么是 LangGraph 开发服务器？

LangGraph 开发服务器是 LangChain 提供的一个强大的本地开发工具，它允许开发者在本地环境中快速构建、测试和调试基于 LangGraph 的 AI Agent 应用。通过简单的命令行启动，即可获得一个完整的开发环境，包括 API 服务、可视化 Studio UI 以及 API 文档。

效果图： 浏览器中输入 https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024

使用火狐浏览器

为什么需要 LangGraph 开发服务器？

传统的 AI Agent 开发往往需要在云端部署才能进行测试，这不仅增加了开发成本，还降低了调试效率。LangGraph 开发服务器解决了这个问题，它提供了：

• 即时反馈：修改代码后立即看到效果，无需等待部署
• 可视化调试：通过 Studio UI 直观查看 Agent 的执行流程
• 本地化开发：所有数据和处理都在本地完成，保障数据安全
• 完整的 API 支持：提供标准的 RESTful API 接口，便于集成

环境准备与安装

在开始使用 LangGraph 开发服务器之前，需要完成以下安装步骤：

1. 安装 Python 环境

LangGraph 要求 Python 3.10 或更高版本。检查您当前的 Python 版本：

python --version

如果版本低于 3.10，请从 Python 官网 下载并安装最新版本。

2. 创建虚拟环境（推荐）

为了避免依赖冲突，建议为项目创建独立的虚拟环境：

Windows (PowerShell):

# 创建虚拟环境
python -m venv .venv

# 激活虚拟环境
.venv\Scripts\Activate.ps1

macOS/Linux:

# 创建虚拟环境
python3 -m venv .venv

# 激活虚拟环境
source .venv/bin/activate

3. 安装项目依赖

进入项目根目录，安装所有必需的依赖包：

# 安装项目依赖（包含开发工具）
pip install -e ".[dev]"

这个命令会安装：

• langgraph>=1.0.0 - LangGraph 核心库
• python-dotenv>=1.0.1 - 环境变量管理
• 开发工具（mypy、ruff 等）

4. 安装 LangGraph CLI

LangGraph 开发服务器需要通过 CLI 工具启动：

# 安装 LangGraph CLI（包含内存模式支持）
pip install "langgraph-cli[inmem]>=0.4.14"

或者，如果您的项目已经在 pyproject.toml 中配置了依赖，可以直接安装开发组：

# 使用 uv（更快的包管理器）
pip install uv
uv sync --group dev

# 或使用 pip
pip install -e "."
pip install langgraph-cli[inmem]

5. 验证安装

安装完成后，验证各个组件是否正确安装：

# 检查 LangGraph CLI
langgraph --version

# 检查 Python 包
python -c "import langgraph; print(langgraph.__version__)"

如果看到版本号输出，说明安装成功。

6. 配置环境变量

创建 .env 文件并配置必要的 API 密钥：

# 复制示例配置文件（如果有）
cp .env.example .env

编辑 .env 文件，填入您的配置：

# LangSmith 监控（可选）
LANGSMITH_PROJECT=your-project-name
LANGSMITH_API_KEY=your-langsmith-key

# LLM 提供商配置（以智谱 AI 为例）
ZHIPU_API_KEY=your-zhipu-api-key
ZHIPU_BASE_URL=https://open.bigmodel.cn/api/paas/v4/

# 或使用其他 LLM 提供商
# OPENAI_API_KEY=your-openai-key
# ALIBABA_API_KEY=your-alibaba-key

注意事项：

• 确保 API 密钥正确且有效
• 不要将 .env 文件提交到版本控制系统
• 在 .gitignore 中添加 .env

7. 常见问题排查

问题 1：pip install 权限错误

Windows:

# 使用 --user 标志
pip install --user langgraph-cli[inmem]

# 或以管理员身份运行 PowerShell

macOS/Linux:

# 使用 --user 标志
pip install --user langgraph-cli[inmem]

# 或使用虚拟环境（推荐）
python3 -m venv .venv
source .venv/bin/activate
pip install langgraph-cli[inmem]

问题 2：依赖冲突

如果遇到依赖冲突，尝试：

# 升级 pip
python -m pip install --upgrade pip

# 清除缓存后重新安装
pip cache purge
pip install -e ".[dev]"

问题 3：langgraph 命令找不到

# 检查 Python Scripts 目录是否在 PATH 中
# Windows: %APPDATA%\Python\Python310\Scripts
# macOS/Linux: ~/.local/bin

# 或者使用 python -m 方式运行
python -m langgraph dev

8. 快速安装清单

如果您想快速开始，可以按顺序执行以下命令：

# 1. 检查 Python 版本
python --version  # 确保 >= 3.10

# 2. 创建并激活虚拟环境
python -m venv .venv
.venv\Scripts\Activate.ps1  # Windows
# source .venv/bin/activate  # macOS/Linux

# 3. 安装项目依赖
pip install -e ".[dev]"

# 4. 安装 LangGraph CLI
pip install "langgraph-cli[inmem]>=0.4.14"

# 5. 配置环境变量
# 编辑 .env 文件，填入 API 密钥

# 6. 验证安装
langgraph --version

# 7. 启动开发服务器
langgraph dev

安装完成后，您就可以使用 langgraph dev 启动开发服务器了！

---

启动命令：langgraph dev

启动 LangGraph 开发服务器非常简单，只需在项目根目录下执行：

langgraph dev

该命令会启动一个开发服务器，默认监听 http://127.0.0.1:2024 端口，提供以下服务：

• API 服务：用于与 Agent 进行交互
• Studio UI：可视化的调试界面
• API 文档：完整的接口说明

实战案例：使用当前项目启动 LangGraph

让我们以一个实际的 LangGraph 项目为例，演示如何配置和启动开发服务器。

项目结构概览

我们的项目采用标准的 Python 包结构：

myopenclaw/
├── src/
│   └── agent/
│       └── multi_agent/
│           └── main_agent.py    # 主 Agent 实现
├── langgraph.json               # LangGraph 配置文件
├── pyproject.toml               # Python 项目配置
├── .env                         # 环境变量配置
└── subagents.yaml               # 子 Agent 配置

关键配置文件解析

1. langgraph.json - 核心配置文件

这是 LangGraph 项目的核心配置文件，定义了项目的依赖、图结构和环境设置：

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "agent": "./src/agent/multi_agent/main_agent.py:agent"
  },
  "env": ".env"
}

配置说明：

• dependencies: 指定项目依赖，"." 表示当前目录
• graphs: 定义 Agent 图的位置，格式为 文件路径:变量名
• env: 指定环境变量文件

2. pyproject.toml - 项目依赖管理

[project]
name = "agent"
version = "0.0.1"
requires-python = ">=3.10"
dependencies = [
    "langgraph>=1.0.0",
    "python-dotenv>=1.0.1",
]

[dependency-groups]
dev = [
    "langgraph-cli[inmem]>=0.4.14",
    ...
]

这里定义了项目所需的依赖包，特别注意 langgraph-cli[inmem] 是开发服务器所必需的。

3. .env - 环境变量配置

LANGSMITH_PROJECT=new-agent
ZHIPU_API_KEY=your_api_key_here
ZHIPU_BASE_URL=https://open.bigmodel.cn/api/paas/v4/

环境变量文件用于配置 API 密钥、基础 URL 和其他敏感信息。

启动步骤详解

步骤 1：安装依赖

首先，确保已安装所有必要的依赖：

pip install -e ".[dev]"

或者单独安装开发工具：

pip install langgraph-cli[inmem]

步骤 2：配置环境变量

编辑 .env 文件，填入你的 API 密钥和其他必要配置。本项目使用智谱 AI 作为 LLM 后端。

步骤 3：启动开发服务器

在项目根目录下执行：

langgraph dev

你会看到类似以下输出：

Starting LangGraph development server...
Server running at http://127.0.0.1:2024
Studio UI available at http://127.0.0.1:2024/studio
API docs at http://127.0.0.1:2024/docs

步骤 4：访问服务

• Studio UI: 打开浏览器访问 http://127.0.0.1:2024/studio，可以直观地查看和调试 Agent 的执行流程
• API 文档: 访问 http://127.0.0.1:2024/docs 查看完整的 API 接口文档
• API 端点: 通过 http://127.0.0.1:2024 与 Agent 进行程序化交互

实际应用场景

启动服务器后，你可以通过 API 与 Agent 进行交互。例如：

curl -X POST http://127.0.0.1:2024/invoke \
  -H "Content-Type: application/json" \
  -d '{"input": "请帮我分析今天的天气情况"}'

或者使用 Python 客户端：

import requests

response = requests.post(
    "http://127.0.0.1:2024/invoke",
    json={"input": "查询最新技术趋势"}
)
print(response.json())

常见问题与解决方案

1. 端口占用问题

如果 2024 端口已被占用，可以通过环境变量指定其他端口：

export LANGGRAPH_PORT=3000
langgraph dev

2. 依赖安装失败

确保使用 Python 3.10 或更高版本，并尝试更新 pip：

python -m pip install --upgrade pip
pip install -e ".[dev]"

3. API 密钥配置错误

检查 .env 文件中的 API 密钥是否正确，确保没有多余的空格或换行符。

总结

LangGraph 开发服务器为 AI Agent 开发提供了极大的便利，通过 langgraph dev 命令即可快速启动本地开发环境。结合合理的配置和清晰的代码结构，开发者可以高效地构建、测试和迭代复杂的 Agent 系统。

通过本文的实践案例，你应该已经掌握了如何配置和启动 LangGraph 开发服务器。现在，你可以开始构建自己的智能 Agent 应用了！

延伸阅读

• LangGraph 官方文档
• DeepAgents 框架介绍
• 智谱 AI API 文档