当前位置：首页 > news >正文

在本机启动 LangGraph 开发服务器：完整指南

news 2026/5/26 14:34:23

在本机启动 LangGraph 开发服务器：完整指南

Posted on 2026-05-26 14:17 work hard work smart 阅读(0) 评论(0) 收藏举报

什么是 LangGraph 开发服务器？

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

效果图：

使用火狐浏览器

为什么需要 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 requestsresponse = 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 开发服务器：完整指南