文章目录
- 1. 项目概述
- 2. 技术栈与核心概念
- 2.1 核心技术栈
- 2.2 关键概念
- 3. 环境准备
- 3.1 系统要求
- 3.2 安装uv包管理器
- 3.3 安装LangGraph Studio（可选）
- 3.4 申请必要API Key
- 4. 项目搭建
- 4.1 创建项目目录与初始化
- 4.2 创建并激活虚拟环境
- 4.3 配置pyproject.toml
- 4.4 安装项目依赖
- 4.5 创建目录结构
- 4.6 配置.gitignore
- 4.7 创建.codespellignore
- 5. 配置管理
- 5.1 创建.env.example（环境变量模板）
- 5.2 创建.env（真实环境变量）
- 5.3 配置langgraph.json（Studio入口）
- 6. 核心代码实现（逐文件）
- 6.1 prompts.py（系统提示词）
- 6.2 state.py（状态结构定义）
- 6.3 context.py（运行时上下文）
- 6.4 utils.py（工具函数）
- 6.5 tools.py（工具集）
- 6.6 graph.py（核心图定义，ReAct循环）
- 6.7 __init__.py（包入口）
- 6.8 标记py.typed（类型提示）
- 7. LangGraph协议集成
- 7.1 核心协议要求
- 7.2 上下文流转流程
- 7.3 与旧版RunnableConfig的差异
- 8. 工具与外部API集成
- 8.1 Tavily搜索集成
- 8.2 多LLM提供商集成
- 8.3 LangSmith追踪（可选）
- 8.4 自定义工具示例
- 9. 测试验证
- 9.1 测试目录结构
- 9.2 conftest.py（pytest配置）
- 9.3 单元测试（test_configuration.py）
- 9.4 集成测试（test_graph.py）
- 9.5 运行测试命令
- 9.6 Lint与类型检查
- 10. 本地运行与调试
- 10.1 LangGraph Studio桌面版
- 10.2 langgraph dev本地服务器
- 10.3 代码直接调用
- 10.4 调试技巧
- 11. CI/CD集成
- 11.1 单元测试CI（unit-tests.yml）
- 11.2 集成测试CI（integration-tests.yml）
- 11.3 配置GitHub Secrets
- 12. 常见问题与扩展
- 12.1 常见问题解决
- 12.2 扩展方向
- 12.3 完整开发流程速查
- 总结
ReAct（Reasoning + Acting）是大模型智能体（Agent）的核心范式，通过“推理决策+工具执行”的循环实现复杂任务处理；而LangGraph作为LangChain生态下的状态机框架，能直观构建Agent的状态流转逻辑，并支持在LangGraph Studio中可视化调试。本文将从0到1完整还原基于LangGraph 1.0+开发ReAct Agent的全流程，涵盖环境准备、项目搭建、核心代码实现、测试验证、CI/CD集成等所有环节，提供可直接复制的命令和代码，即使是入门开发者也能快速上手。
1. 项目概述
本项目是基于LangGraph实现的ReAct Agent模板，可在LangGraph Studio中可视化运行，核心工作流程如下：
- 接收用户查询（query）；
- LLM推理决定下一步动作（调用工具或直接回答）；
- 执行工具（默认集成Tavily搜索）；
- 观察工具执行结果；
- 循环2-4步直至给出最终答案。
项目最终文件结构如下：
react-agent/ ├── .github/workflows/ │ ├── unit-tests.yml # 单元测试 CI │ └── integration-tests.yml # 集成测试 CI ├── src/react_agent/ │ ├── __init__.py # 包入口，导出 graph │ ├── context.py # 运行时上下文（可配置参数
)
