【LangGraph】House_Agent 实战（一）：架构与环境配置

BU摆烂会噶2026-05-22 10:10

【LangGraph】LangGraph 实战（一）：项目架构与环境配置

    • 一、项目背景
      • [1.1 为什么做这个项目？](#1.1 为什么做这个项目？)
      • [1.2 项目功能](#1.2 项目功能)
      • [1.3 最终效果展示](#1.3 最终效果展示)
    • 二、技术选型
      • [2.1 为什么选择 LangGraph？](#2.1 为什么选择 LangGraph？)
      • [2.2 核心概念回顾](#2.2 核心概念回顾)
    • 三、项目架构设计
      • [3.1 整体架构](#3.1 整体架构)
      • [3.2 主图 Mermaid 流程图](#3.2 主图 Mermaid 流程图)
      • [3.3 子图 Mermaid 流程图](#3.3 子图 Mermaid 流程图)
      • [3.4 模块职责](#3.4 模块职责)
    • 四、环境配置详解
      • [4.1 langgraph.json 配置](#4.1 langgraph.json 配置)
        • [4.1.1 配置说明：](#4.1.1 配置说明：)
        • [4.1.2 图入口格式：模块路径------>变量名](#4.1.2 图入口格式：模块路径——>变量名)
      • [4.2 环境变量配置](#4.2 环境变量配置)
      • [4.3 项目目录整体结构](#4.3 项目目录整体结构)
      • [4.4 依赖管理](#4.4 依赖管理)
    • 五、搭建项目
      • [5.1 安装 LangGraph CLI](#5.1 安装 LangGraph CLI)
      • [5.2 安装项目依赖](#5.2 安装项目依赖)
      • [5.3 启动 LangGraph Server](#5.3 启动 LangGraph Server)
      • [5.4 启动 FastAPI 代理](#5.4 启动 FastAPI 代理)
      • [5.5 访问应用](#5.5 访问应用)
      • [5.6 常见问题排查](#5.6 常见问题排查)
    • 六、本文总结

一、项目背景

1.1 为什么做这个项目？

在 AI Agent 开发领域，LangGraph 作为一个有状态的多参与者框架，提供了强大的工作流编排能力，为了深入学习 LangGraph 的核心功能，也是对之前的学习做一个总结，我设计并实现了一个简单的 AI 智能租房助手 项目

这个项目涵盖了 LangGraph 的核心特性：

  • 工作流编排与路由
  • 子图设计与状态共享
  • 持久化与检查点
  • 人工干预与中断
  • 工具调用与数据库交互
  • 流式输出

1.2 项目功能

用户可以通过自然语言与助手交互，实现以下功能：

功能 说明 示例
房源推荐 根据用户需求查询数据库推荐房源 "帮我推荐北京 3000-5000 的房子"
房源预定 收集用户信息并生成预定工单 "我要预定长安花园"
信息查询 查询用户的预定记录和偏好 "看看我的历史记录"
常规问答 回答租房相关的一般问题 "租房需要注意什么？"

1.3 最终效果展示

（此处留白，后续插入实际运行效果）

二、技术选型

2.1 为什么选择 LangGraph？

特性 LangGraph 其他框架
状态管理 内置状态图 需要手动管理
流程控制 条件边、循环 有限支持
持久化 内置 Checkpoint 需要自行实现
人工干预 原生 interrupt 需要额外处理
可视化 Mermaid 流程图 有限支持

2.2 核心概念回顾

LangGraph 的核心概念：

  • State（状态）：贯穿整个图的数据结构
  • Node（节点）：执行具体逻辑的函数
  • Edge（边）：节点之间的连接
  • Conditional Edge（条件边）：根据状态决定路由
  • Checkpoint（检查点）：自动保存的状态快照
  • Interrupt（中断）：暂停执行等待人工输入

三、项目架构设计

3.1 整体架构

项目采用 主图 + 子图 的架构模式。其中推荐流程以子图形式嵌入主图，而预定流程的节点则直接集成在主图中------这是有意为之的设计，原因会在之后几篇详细说明

3.2 主图 Mermaid 流程图

网页搜索Mermaid在线编辑器输入一下指令生成Mermaid 图：

python 复制代码 
# 生成命令
print(graph.get_graph(xray=True).draw_mermaid())

3.3 子图 Mermaid 流程图

推荐子图：

python 复制代码 
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 的核心配置文件，定义了图的入口和依赖：

json 复制代码 
{
  "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 文件，配置必要的环境变量：

bash 复制代码 
# LangSmith 配置（可选，用于调试和追踪）
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your_langsmith_api_key_here
LANGCHAIN_PROJECT=house-agent

# LLM 配置
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_NAME=houser_agent
DB_USER=root
DB_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 依赖管理

需要安装的一些必要依赖：

txt 复制代码 
# 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 或更高版本

bash 复制代码 
pip install -U "langgraph-cli[inmem]"

# 验证安装情况
langgraph --help

CLI 指令说明：

指令 说明
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 安装项目依赖

bash 复制代码 
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows

# 安装依赖
pip install -r requirements.txt

5.3 启动 LangGraph Server

这里我们选择本地部署终端输入langgraph dev命令：

bash 复制代码 
# 开发模式启动
langgraph dev

# 指定端口
langgraph dev --port 2024

举个例子，启动成功后，会看到类似输出：

复制代码 
(.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 代理

再开个终端输入以下命令：

bash 复制代码 
# 启动代理服务
python server.py

# 或使用 uvicorn
uvicorn server:app --host 0.0.0.0 --port 8000

举个例子，启动成功后，会看到类似输出：

复制代码 
(.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 访问应用

项目启动成功后，可通过以下方式进行调试与交互：

5.6 常见问题排查

问题 原因 解决方案
连接失败 LangGraph Server 未启动 先启动 langgraph dev
API Key 错误 环境变量配置错误 检查 .env 文件
数据库连接失败 数据库未启动或配置错误 检查数据库服务和配置
模块导入错误 依赖未安装 运行 pip install -r requirements.txt

六、本文总结

本文介绍了 AI 智能租房助手项目的整体架构和环境配置：

  1. 项目背景：通过实战项目学习 LangGraph 核心功能
  2. 技术选型：LangGraph 提供了状态管理、流程控制、持久化等完整能力
  3. 架构设计：主图 + 子图模式，职责清晰，易于扩展
  4. 环境配置：langgraph.json、环境变量、依赖管理
  5. 搭建项目：LangGraph CLI 安装、项目依赖、启动运行

下一篇文章：我们将深入探讨状态设计与主图构建，学习如何设计清晰的状态结构和实现智能路由。

本文是 House_Agent 实战系列的第一篇，制作不易
如果觉得有帮助，欢迎点赞和分享！
咱们下篇再见~

相关推荐
小小测试开发2 小时前
OpenAI 模型攻克离散几何 80 年难题：Erdős 单位距离猜想被 AI 证明
人工智能·算法·机器学习
woniu_buhui_fei2 小时前
单体服务拆分微服务
微服务·架构
moonsims2 小时前
从“传感器融合”升级为“多机器人约束融合系统”-Factor Graph 多约束融合
人工智能·算法
heimeiyingwang2 小时前
【架构实战】日志体系ELK：集中化日志管理实践
elk·架构·wpf
tedcloud1232 小时前
agent-skills部署教程：打造工程化AI Agent系统
服务器·人工智能·系统架构·powerpoint·dreamweaver
测试员周周2 小时前
【Appium 系列】第15节-视觉测试 — 截图、对比、视觉回归
人工智能·python·数据挖掘·回归·appium·测试用例·测试覆盖率
pixle02 小时前
LangChain v1.2 Text-to-SQL 实战：从入门到生产级部署
sql·langchain·agent·智能助手·text-to-sql
Dfreedom.2 小时前
模型剪枝完全指南：从理论到实践，打造高效深度学习模型
人工智能·算法·机器学习·剪枝·模型加速
开始脱发的自然卷2 小时前
用 Excel 手算 LSTM：从四个门到梯度下降的完整过程
人工智能
热门推荐
01GitHub 镜像站点02Codex 接入 DeepSeek API 完整配置文档03CC-Switch & Claude 基于 Linux 服务器安装使用指南04【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法05【AI】2026 年具身智能模型和世界模型总结06装上就回不去了：CodeGraph 让 AI 编程效率飙升 92%，它到底做了什么？07几个好用的ip纯净度检测网站08裂开！ChatGPT 居然开始要手机号验证，附详细解决方法09用了半年 OpenRouter，我换到了 Ofox.ai — 两个 AI API 聚合平台的真实对比10codex app每次打开重连5次Reconnecting问题解决