【LangGraph】House_Agent 实战（一）：架构与环境配置
【LangGraph】LangGraph 实战（一）：项目架构与环境配置
- 一、项目背景
- 1.1 为什么做这个项目？
- 1.2 项目功能
- 二、技术选型
- 2.1 为什么选择 LangGraph？
- 2.2 核心概念回顾
- 三、项目架构设计
- 3.1 整体架构
- 3.2 主图 Mermaid 流程图
- 3.3 子图 Mermaid 流程图
- 3.4 模块职责
- 四、环境配置详解
- 4.1 langgraph.json 配置
- 4.1.1 配置说明：
- 4.1.2 图入口格式：模块路径——>变量名
- 4.2 环境变量配置
- 4.3 项目目录整体结构
- 4.4 依赖管理
- 五、搭建项目
- 5.1 安装 LangGraph CLI
- 5.2 安装项目依赖
- 5.3 启动 LangGraph Server
- 5.4 启动 FastAPI 代理
- 5.5 访问应用
- 5.6 常见问题排查
- 六、本文总结
一、项目背景
1.1 为什么做这个项目？
在 AI Agent 开发领域，LangGraph 作为一个有状态的多参与者框架，提供了强大的工作流编排能力，为了深入学习 LangGraph 的核心功能，也是对之前的学习做一个总结，我设计并实现了一个简单的AI 智能租房助手项目
这个项目涵盖了 LangGraph 的核心特性：
- 工作流编排与路由
- 子图设计与状态共享
- 持久化与检查点
- 人工干预与中断
- 工具调用与数据库交互
- 流式输出
1.2 项目功能
用户可以通过自然语言与助手交互，实现以下功能：
| 功能 | 说明 | 示例 |
|---|---|---|
| 房源推荐 | 根据用户需求查询数据库推荐房源 | “帮我推荐北京 3000-5000 的房子” |
| 房源预定 | 收集用户信息并生成预定工单 | “我要预定长安花园” |
| 信息查询 | 查询用户的预定记录和偏好 | “看看我的历史记录” |
| 常规问答 | 回答租房相关的一般问题 | “租房需要注意什么？” |
二、技术选型
2.1 为什么选择 LangGraph？
| 特性 | LangGraph | 其他框架 |
|---|---|---|
| 状态管理 | 内置状态图 | 需要手动管理 |
| 流程控制 | 条件边、循环 | 有限支持 |
| 持久化 | 内置 Checkpoint | 需要自行实现 |
| 人工干预 | 原生 interrupt | 需要额外处理 |
| 可视化 | Mermaid 流程图 | 有限支持 |
2.2 核心概念回顾
LangGraph 的核心概念：
- State（状态）：贯穿整个图的数据结构
- Node（节点）：执行具体逻辑的函数
- Edge（边）：节点之间的连接
- Conditional Edge（条件边）：根据状态决定路由
- Checkpoint（检查点）：自动保存的状态快照
- Interrupt（中断）：暂停执行等待人工输入
三、项目架构设计
3.1 整体架构
项目采用主图 + 子图的架构模式。其中推荐流程以子图形式嵌入主图，而预定流程的节点则直接集成在主图中——这是有意为之的设计，原因会在之后几篇详细说明
3.2 主图 Mermaid 流程图
网页搜索Mermaid在线编辑器输入一下指令生成Mermaid 图：
# 生成命令print(graph.get_graph(xray=True).draw_mermaid())3.3 子图 Mermaid 流程图
推荐子图：
print(recommend_graph.get_graph(xray=True).draw_mermaid())3.4 模块职责
| 模块 | 职责 | 状态字段 | 形式 |
|---|---|---|---|
| 主图 | 智能路由、意图识别、预定流程 | user_intent, reserve, title, phone_number, id_card | 主图直接节点 |
| 推荐子图 | 查询数据库推荐房源 | city, district, budget, room_type | 子图 |
| 扩展问答 | 常规问答 | messages | 单节点 |
四、环境配置详解
4.1 langgraph.json 配置
这是 LangGraph 的核心配置文件，定义了图的入口和依赖：
{"dependencies":["."],"graphs":{"house_agent":"./src/agent/graph.py:graph","recommend_agent":"./src/agent/recommend.py:recommend_graph"},"env":".env"}4.1.1 配置说明：
| 字段 | 说明 |
|---|---|
dependencies | Python 依赖路径 |
graphs | 图的名称和入口点映射 |
env | 环境变量文件路径 |
4.1.2 图入口格式：模块路径——>变量名
例如"./src/agent/graph.py:graph"表示：
- 文件路径：
./src/agent/graph.py - 导出变量：
graph（已编译的 CompiledGraph）
注意：
本次设计预定流程和扩展问答的节点直接集成在主图中，不需要单独注册为独立的图
4.2 环境变量配置
创建.env文件，配置必要的环境变量：
# LangSmith 配置（可选，用于调试和追踪）LANGCHAIN_TRACING_V2=trueLANGCHAIN_API_KEY=your_langsmith_api_key_hereLANGCHAIN_PROJECT=house-agent# LLM 配置OPENAI_API_KEY=your_openai_api_key_hereOPENAI_BASE_URL=https://api.openai.com/v1# 数据库配置DB_HOST=localhostDB_PORT=3306DB_NAME=houser_agentDB_USER=rootDB_PASSWORD=your_db_password_here需要注意的是：：
- 不要将
.env文件提交到 Git！！！ - 使用
.gitignore忽略敏感文件！！！ - 生产环境使用环境变量或密钥管理服务！！！
4.3 项目目录整体结构
house_agent/ ├── src/ │ └── agent/ │ ├── common/ │ │ ├── __init__.py │ │ ├── context.py # 运行上下文定义 │ │ ├── llm.py # LLM 模型配置 │ │ └── store.py # 存储相关模型 │ ├── node/ │ │ ├── __init__.py │ │ ├── main.py # 主图节点（意图识别、偏好查询等） │ │ ├── recommend.py # 推荐子图节点 │ │ ├── reserve.py # 预定流程节点（直接集成在主图） │ │ └── extend.py # 扩展问答节点 │ ├── state/ │ │ ├── __init__.py │ │ ├── main.py # 主图状态 │ │ ├── recommend.py # 推荐子图状态 │ │ └── reserve.py # 预定流程状态 │ ├── graph.py # 主图定义（含预定流程） │ └── recommend.py # 推荐子图定义 ├── frontend/ │ └── index.html # 前端页面 ├── static/ # 静态资源 ├── server.py # FastAPI 代理服务 ├── langgraph.json # LangGraph 配置 ├── .env # 环境变量 └── requirements.txt # Python 依赖4.4 依赖管理
需要安装的一些必要依赖：
# requirements.txt langgraph>=0.2.0 langchain>=0.2.0 langchain-openai>=0.1.0 langchain-community>=0.2.0 fastapi>=0.100.0 uvicorn>=0.23.0 python-dotenv>=1.0.0 pymysql>=1.1.0五、搭建项目
5.1 安装 LangGraph CLI
LangGraph CLI 是用于构建和运行 LangGraph 应用程序的命令行工具
需要 Python 3.11 或更高版本
pipinstall-U"langgraph-cli[inmem]"# 验证安装情况langgraph--helpCLI 指令说明：
| 指令 | 说明 |
|---|---|
langgraph dev | 启动一个轻量级本地开发服务器（无需 Docker），非常适合快速测试 |
langgraph build | 构建 LangGraph API 服务器的 Docker 镜像以便部署 |
langgraph dockerfile | 根据配置导出 Dockerfile，用于自定义构建 |
langgraph up | 在本地 Docker 启动 LangGraph API 服务器（需要 Docker 和 LangSmith API 密钥） |
启动后的 LangGraph 服务器会公开以下核心概念：
- 助手（Assistants）：图的配置实例
- 线程（Threads）：一组运行的累积输出，实际表示为一个会话
- 线程执行（Thread Runs）：对线程上图/助手的调用，会更新线程的状态
5.2 安装项目依赖
# 创建虚拟环境python-mvenv venvsourcevenv/bin/activate# Linux/Mac# 或venv\Scripts\activate# Windows# 安装依赖pipinstall-rrequirements.txt5.3 启动 LangGraph Server
这里我们选择本地部署终端输入langgraph dev命令：
# 开发模式启动langgraph dev# 指定端口langgraph dev--port2024举个例子，启动成功后，会看到类似输出：
(.venv) PS D:\PythonProject\house_agent> langgraph dev INFO:langgraph_api.cli: Welcome to ╦ ┌─┐┌┐┌┌─┐╔═╗┬─┐┌─┐┌─┐┬ ┬ ║ ├─┤││││ ┬║ ╦├┬┘├─┤├─┘├─┤ ╩═╝┴ ┴┘└┘└─┘╚═╝┴└─┴ ┴┴ ┴ ┴ - 🚀 API: http://localhost:2024 - 🎨 Studio UI: https://smith.langchain.com/studio/?baseUrl=http://localhost:2024 - 📚 API Docs: http://localhost:2024/docs This in-memory server is designed for development and testing. For production use, please use LangSmith Deployment.5.4 启动 FastAPI 代理
再开个终端输入以下命令：
# 启动代理服务python server.py# 或使用 uvicornuvicorn server:app--host0.0.0.0--port8000举个例子，启动成功后，会看到类似输出：
(.venv) PS D:\PythonProject\house_agent> python server.py INFO: Started server process [22612] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)5.5 访问应用
项目启动成功后，可通过以下方式进行调试与交互：
- 前端页面：http://localhost:8000
- API 文档：http://localhost:8000/docs
- LangGraph Studio 可视化调试：使用提供的 Studio 链接，对工作流进行可视化调试与优化
5.6 常见问题排查
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 连接失败 | LangGraph Server 未启动 | 先启动langgraph dev |
| API Key 错误 | 环境变量配置错误 | 检查.env文件 |
| 数据库连接失败 | 数据库未启动或配置错误 | 检查数据库服务和配置 |
| 模块导入错误 | 依赖未安装 | 运行pip install -r requirements.txt |
六、本文总结
本文介绍了 AI 智能租房助手项目的整体架构和环境配置：
- 项目背景：通过实战项目学习 LangGraph 核心功能
- 技术选型：LangGraph 提供了状态管理、流程控制、持久化等完整能力
- 架构设计：主图 + 子图模式，职责清晰，易于扩展
- 环境配置：langgraph.json、环境变量、依赖管理
- 搭建项目：LangGraph CLI 安装、项目依赖、启动运行
下一篇文章：我们将深入探讨状态设计与主图构建，学习如何设计清晰的状态结构和实现智能路由。
本文是 House_Agent 实战系列的第一篇，制作不易
如果觉得有帮助，欢迎点赞和分享！
咱们下篇再见~