本地环境部署LangGraph
运行LangGraph本地服务器教程总结
该教程详细介绍了在本地环境搭建、运行LangGraph应用的完整流程，涵盖依赖安装、项目创建、环境配置、服务器启动及测试验证，同时提供后续部署与进阶学习方向，适用于开发者快速搭建LangGraph应用的本地开发环境，具体内容如下：
一、前提条件
需提前准备LangSmith API密钥（可免费注册获取），用于后续应用的追踪、调试与可观测性支持。
二、核心操作步骤
1. 安装LangGraph CLI（命令行工具）
LangGraph CLI是创建、管理LangGraph项目的核心工具，需确保Python版本≥3.11，安装命令如下：
pip install --upgrade "langgraph-cli[inmem]"
[inmem]：表示同时安装内存存储相关依赖，用于本地开发时的临时状态存储。
2. 创建LangGraph应用（基于模板）
通过CLI从官方模板创建新项目，快速生成可扩展的基础架构（示例使用new-langgraph-project-python模板，为单节点应用，便于后续自定义逻辑）：
langgraph new path/to/your/app --template new-langgraph-project-python
- 模板选择说明：若未指定
--template参数，执行langgraph new path/to/your/app后会弹出交互式菜单，可从多个可用模板中选择（如多智能体模板、带记忆功能的模板等）。
3. 安装项目依赖（编辑模式）
进入项目根目录，以“编辑模式”（-e）安装依赖，确保本地代码修改能实时被服务器识别（无需重复安装）：
# 进入项目目录
cd path/to/your/app
# 安装依赖
pip install -e .
4. 配置环境变量（创建.env文件）
项目根目录会生成.env.example示例文件，需基于该文件创建.env并填充关键配置（核心为LangSmith API密钥）：
- 复制
.env.example内容到新创建的.env文件； - 替换
LANGSMITH_API_KEY为实际密钥，示例：LANGSMITH_API_KEY=lsv2... # 替换为你的LangSmith API密钥
5. 启动本地LangGraph服务器
通过langgraph dev命令启动本地API服务器，默认启用内存模式（仅适用于开发与测试，生产环境需切换至持久化存储后端）：
langgraph dev
启动成功后输出信息
启动成功后会显示3个关键链接，分别对应API地址、文档地址与可视化UI地址：
> Ready!
>
> - API: http://localhost:2024/ # 本地API接口地址
>
> - Docs: http://localhost:2024/docs # API文档（Swagger风格，可查看所有接口）
>
> - LangGraph Studio Web UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024 # 可视化调试UI
- Safari兼容性处理：若使用Safari浏览器，本地localhost连接可能受限，需添加
--tunnel参数创建安全隧道：langgraph dev --tunnel
6. 测试应用（通过LangGraph Studio）
LangGraph Studio是专为LangGraph设计的可视化UI，支持本地应用的交互、调试与流程可视化，操作步骤如下：
- 访问
langgraph dev输出中的“LangGraph Studio Web UI”链接（如https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024）； - 在Studio中可直接与LangGraph应用交互（如发送用户消息）、查看状态流转、调试工具调用逻辑；
- 若服务器使用自定义主机/端口（非默认localhost:2024），需手动修改链接中的
baseUrl参数（如baseUrl=http://192.168.1.100:8080）。
7. 测试API接口（3种方式）
除可视化UI外，可通过Python SDK（同步/异步）或REST API直接调用本地服务器接口，验证应用功能。
方式1：Python SDK（异步）
- 安装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():# 流式调用API，查询“What is LangGraph?”async for chunk in client.runs.stream(None, # thread_id为None，表示“无线程”单次调用"agent", # 智能体名称，在项目langgraph.json中定义input={"messages": [{"role": "human", "content": "What is LangGraph?"}]},):print(f"接收事件类型: {chunk.event}...")print(chunk.data)print("\n\n")# 执行异步函数 asyncio.run(main())
方式2：Python SDK（同步）
- 安装SDK（同上，已安装可跳过）；
- 发送同步请求：
from langgraph_sdk import get_sync_client# 连接本地服务器（同步客户端） client = get_sync_client(url="http://localhost:2024")# 流式调用API for chunk in client.runs.stream(None, # 无线程ID"agent", # 智能体名称input={"messages": [{"role": "human", "content": "What is LangGraph?"}]},stream_mode="messages-tuple", # 流式输出模式：按消息元组返回 ):print(f"接收事件类型: {chunk.event}...")print(chunk.data)print("\n\n")
方式3：REST API（curl命令）
通过curl发送POST请求，直接调用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\"}"
assistant_id: 对应智能体名称（与SDK中的“agent”一致）；stream_mode: 流式输出格式，此处为“消息元组”。
三、后续步骤
本地服务器运行成功后，可进一步探索LangGraph的部署与高级功能：
- 部署快速入门：通过LangGraph Platform将应用部署到生产环境（需配置持久化存储，如PostgreSQL）；
- LangGraph Platform概述：学习平台核心概念（如多智能体协作、大规模部署优化等）；
- API参考文档：访问
http://localhost:2024/docs或官方文档，深入了解所有API的参数与使用场景； - Python SDK参考：探索SDK的更多功能（如对话线程管理、状态查询、批量调用等）。
四、关键注意事项
- 内存模式局限性：
langgraph dev默认的内存模式下，服务器重启后所有状态（如对话历史、检查点）会丢失，生产环境需替换为SqliteSaver、PostgresSaver等持久化存储； - 智能体名称配置：代码中使用的“agent”是默认智能体名称，可在项目根目录的
langgraph.json中修改或新增智能体； - LangSmith的作用：LangSmith不仅提供API密钥，还用于追踪应用运行轨迹、调试错误、评估智能体性能，是LangGraph开发的重要辅助工具。