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

【LangGraph】LangGraph 实战一项目架构与环境配置一、项目背景1.1 为什么做这个项目1.2 项目功能二、技术选型2.1 为什么选择 LangGraph2.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 CLI5.2 安装项目依赖5.3 启动 LangGraph Server5.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(xrayTrue).draw_mermaid())3.3 子图 Mermaid 流程图推荐子图print(recommend_graph.get_graph(xrayTrue).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 配置说明字段说明dependenciesPython 依赖路径graphs图的名称和入口点映射env环境变量文件路径4.1.2 图入口格式模块路径——变量名例如./src/agent/graph.py:graph表示文件路径./src/agent/graph.py导出变量graph已编译的 CompiledGraph注意本次设计预定流程和扩展问答的节点直接集成在主图中不需要单独注册为独立的图4.2 环境变量配置创建.env文件配置必要的环境变量# LangSmith 配置可选用于调试和追踪LANGCHAIN_TRACING_V2trueLANGCHAIN_API_KEYyour_langsmith_api_key_hereLANGCHAIN_PROJECThouse-agent# LLM 配置OPENAI_API_KEYyour_openai_api_key_hereOPENAI_BASE_URLhttps://api.openai.com/v1# 数据库配置DB_HOSTlocalhostDB_PORT3306DB_NAMEhouser_agentDB_USERrootDB_PASSWORDyour_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 langgraph0.2.0 langchain0.2.0 langchain-openai0.1.0 langchain-community0.2.0 fastapi0.100.0 uvicorn0.23.0 python-dotenv1.0.0 pymysql1.1.0五、搭建项目5.1 安装 LangGraph CLILangGraph CLI 是用于构建和运行 LangGraph 应用程序的命令行工具需要 Python 3.11 或更高版本pipinstall-Ulanggraph-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/?baseUrlhttp://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 CTRLC to quit)5.5 访问应用项目启动成功后可通过以下方式进行调试与交互前端页面http://localhost:8000API 文档http://localhost:8000/docsLangGraph Studio 可视化调试使用提供的 Studio 链接对工作流进行可视化调试与优化5.6 常见问题排查问题原因解决方案连接失败LangGraph Server 未启动先启动langgraph devAPI Key 错误环境变量配置错误检查.env文件数据库连接失败数据库未启动或配置错误检查数据库服务和配置模块导入错误依赖未安装运行pip install -r requirements.txt六、本文总结本文介绍了 AI 智能租房助手项目的整体架构和环境配置项目背景通过实战项目学习 LangGraph 核心功能技术选型LangGraph 提供了状态管理、流程控制、持久化等完整能力架构设计主图 子图模式职责清晰易于扩展环境配置langgraph.json、环境变量、依赖管理搭建项目LangGraph CLI 安装、项目依赖、启动运行下一篇文章我们将深入探讨状态设计与主图构建学习如何设计清晰的状态结构和实现智能路由。本文是 House_Agent 实战系列的第一篇制作不易如果觉得有帮助欢迎点赞和分享咱们下篇再见~