文章目录1. 项目概述2. 技术栈与核心概念2.1 核心技术栈2.2 关键概念3. 环境准备3.1 系统要求3.2 安装uv包管理器3.3 安装LangGraph Studio（可选）3.4 申请必要API Key4. 项目搭建4.1 创建项目目录与初始化4.2 创建并激活虚拟环境4.3 配置pyproject.toml4.4 安装项目依赖4.5 创建目录结构4.6 配置.gitignore4.7 创建.codespellignore5. 配置管理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 Secrets12. 常见问题与扩展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 # 运行时上下文（可配置参数