# agent-learn-langchain-langgraph

**Repository Path**: zzhpalus/agent-learn-langchain-langgraph

## Basic Information

- **Project Name**: agent-learn-langchain-langgraph
- **Description**: 学习langchain和langgraph项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-02
- **Last Updated**: 2026-08-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🤖 LangGraph 智能体全栈实战项目

> 理解原理 > 跑通 Demo > 前后端成品

从零到一，循序渐进掌握 LangGraph 核心能力的三个智能体项目。

---

## 📚 技术栈

| 层级 | 技术选型 |
|------|----------|
| 智能体框架 | LangGraph + LangChain |
| 状态管理 | StateGraph + TypedDict |
| 持久化 | SqliteSaver（Checkpoint） |
| 后端接口 | Python FastAPI |
| 前端 | React + Vite + TypeScript |
| UI 组件 | Ant Design / Shadcn UI |
| 向量数据库 | ChromaDB |
| 大模型 | 通义千问（OpenAI 兼容格式） |
| 流式输出 | SSE（Server-Sent Events） |

---

## 🗂️ 项目结构

```
agent-learn/
├── rag-qa/                    # 阶段1：文档问答自检索 RAG 循环工作流
│   ├── backend/               # FastAPI 后端
│   ├── frontend/              # React 前端
│   └── docs/                  # 架构设计文档
├── article-write/             # 阶段2：周报文案创作（Human-in-the-loop）
│   ├── backend/
│   ├── frontend/
│   └── docs/
├── travel-agent/              # 阶段3：旅行规划多智能体（Subgraph 子图）
│   ├── backend/
│   ├── frontend/
│   └── docs/
├── .env                       # 全局环境变量（API Key 等）
├── CLAUDE.md                  # Claude Code 项目级规范
└── README.md                  # 本文件
```

---

## 🛤️ 三阶段开发路线

### 阶段1：文档问答自检索 RAG 循环工作流（地基）

**学习目标：** 自定义 State、条件路由、循环重试、LLM 自我校验、防死循环计数器

| 轮次 | 交付内容 | 关键知识点 |
|------|----------|------------|
| 第1轮 | 纯架构：Mermaid 流程图 + RAGState 结构 + 节点职责 + 路由逻辑 | 架构思维、数据流设计 |
| 第2轮 | 基础层：State 定义 + ChromaDB 工具类 + .env 读取代码 | TypedDict 状态定义、ChromaDB 集成 |
| 第3轮 | 节点层：所有 node 函数 + Prompt 模板 | LLM 节点编写、Prompt Engineering |
| 第4轮 | 构图层：StateGraph 构建、条件边、循环闭环、编译 | 条件路由、循环图、Mermaid 导出 |
| 第5轮 | 工程层：FastAPI 接口封装 + React 前端页面 + 联调测试 | SSE 流式、前后端联调 |

**核心工作流：**
```
用户提问 → 向量检索 → LLM 生成答案 → 自我校验 → [通过] 返回答案
                                          ↓ [不通过且未超限]
                                        重试循环（带计数器防死循环）
```

---

### 阶段2：周报文案创作（Human-in-the-loop + Checkpoint 持久化）

**学习目标：** 会话中断暂停、人工介入 update_state、Sqlite 持久化、重启恢复任务

| 轮次 | 交付内容 | 关键知识点 |
|------|----------|------------|
| 第1轮 | 架构：流程图 + WritingState + interrupt 中断方案 | interrupt() API、中断恢复原理 |
| 第2轮 | 基础：State 定义 + Checkpointer 初始化 | SqliteSaver、thread_id 会话隔离 |
| 第3轮 | 节点：大纲生成 / 写作 / 润色 / 自检节点 | 多节点协作、Prompt 模板链 |
| 第4轮 | 核心：中断暂停、前端选择大纲后恢复执行逻辑 | update_state、图恢复机制 |
| 第5轮 | 工程：后端会话接口 + 前端弹窗选择、持久化会话复用 | 会话持久化、页面刷新恢复 |

**核心工作流：**
```
用户输入需求 → AI 生成3套大纲 → ⏸️ interrupt() 暂停
                                      ↓
                              前端弹窗人工选择大纲
                                      ↓
                        resume 恢复执行 → 写作 → 润色 → 自检 → 输出成稿
```

---

### 阶段3：旅行规划四子多智能体（Subgraph 子图 + 统筹 Master）

**学习目标：** 子图封装、多 Agent 调度、并行执行、参数修改自动重算

| 轮次 | 交付内容 | 关键知识点 |
|------|----------|------------|
| 第1轮 | 顶层架构：主图 + 4 个子图嵌套 Mermaid 大图 + TravelState | Subgraph 嵌套、顶层 State 设计 |
| 第2轮 | 子图逐个开发：交通 → 食宿 → 游玩 → 预算 | 独立 Subgraph 封装与调试 |
| 第3轮 | Master 主图：并行调用、结果汇总、need_recalculate 重算逻辑 | 并行节点、条件重算路由 |
| 第4轮 | 后端封装：参数修改触发重跑接口 | 参数对比、增量重算 |
| 第5轮 | 前端成品：表单录入、重新规划、行程卡片全套页面 | 表单交互、结构化展示 |

**核心工作流：**
```
用户填写表单（目的地/天数/预算/风格）
         ↓
    Master 主图调度
    ┌────┼────┬────┐
    ↓    ↓    ↓    ↓
  交通  食宿  游玩  预算    ← 4个 Subgraph 并行执行
    └────┼────┴────┘
         ↓
    结果汇总 → 是否需要重算？ → [是] 重新调度  → 输出行程卡片
                          → [否] 最终输出
```

---

## 🚀 快速开始

### 环境准备

```bash
# 1. 创建虚拟环境
python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Mac/Linux

# 2. 安装依赖（各阶段独立）
cd rag-qa/backend
pip install -r requirements.txt

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 填入通义千问 API Key
```

### 启动服务

```bash
# 后端（每个阶段独立启动）
cd rag-qa/backend
uvicorn main:app --reload --port 8000

# 前端
cd rag-qa/frontend
npm install
npm run dev
```

---

## 🔑 核心学习要点

| 能力 | 对应阶段 | 核心 API / 概念 |
|------|----------|-----------------|
| 自定义状态 | 阶段1 | `TypedDict` + `StateGraph` |
| 条件路由 | 阶段1 | `add_conditional_edges()` |
| 循环重试 | 阶段1 | 图中环路 + 计数器 |
| LLM 自我校验 | 阶段1 | 条件节点判断输出质量 |
| 会话中断 | 阶段2 | `interrupt()` API |
| 人工介入 | 阶段2 | `graph.update_state()` |
| 持久化 | 阶段2 | `SqliteSaver` + `thread_id` |
| 子图封装 | 阶段3 | `Subgraph` 独立编译 |
| 并行调度 | 阶段3 | Master 图并行节点 |
| 参数重算 | 阶段3 | `need_recalculate` 条件边 |

---

## ⚠️ 开发铁律

1. **分阶段迭代交付**，禁止一次性输出完整项目
2. 每轮只输出当前模块，下一轮基于上一轮增量开发
3. 架构阶段只出流程图 + 数据结构 + 执行逻辑，**不写代码**
4. LangGraph 统一 `StateGraph + TypedDict`，弃用 MessageGraph
5. 状态更新用**返回字典**局部更新，禁止原地修改 state
6. 所有代码带详尽中文注释，底层原理和坑点行内标注
7. 每个模块交付后输出【核心知识点】+【高频踩坑点清单】

---

## 📖 参考文档

- [LangChain 中文文档](https://docs.langchain.org.cn/oss/python/langchain/overview)
- [LangGraph 中文文档](https://docs.langchain.org.cn/oss/python/langgraph/overview)

---

> 🧑‍💻 Built for hao总 — 循序渐进，理解原理优先