Agent 框架新手入门与实战部署指南

Agent 框架学习需求手册

0. 如何使用本手册

V1 是地基：只做纯编排，不引入知识库，先把单 Agent 的 LLM 调用、工具定义、结构化输出、循环控制搞清楚。
V2 是落地：加入知识库、文件处理管线、查询正确性保障，这才是真实业务里 Agent 的价值所在。
每完成一项，把 [ ] 改成 [x]，并在对应框架上各实现一遍，最后形成「同一问题的多种解法」对比笔记。
工具全部用 mock 数据，学习阶段不接真实 API，避免外部依赖干扰。

第一部分 V1：纯编排版（先跑通 Agent 编排）

1.1 项目背景

用户输入目的地、出行天数、预算、个人偏好，系统自动产出一份结构化周末行程规划（JSON 格式）。

目标：覆盖 Agent 框架的五个核心概念------工具调用、结构化输出、多 Agent 协作、条件分支、循环控制。

1.2 功能需求

Agent 1：信息收集 Agent（Search Agent）

输入：目的地、天数
职责：调用工具获取三类信息 ------ 当地天气、热门景点清单、当地特色美食
学习要点：如何定义工具（Tool）并让 Agent 调用；工具结果如何结构化返回

Agent 2：规划 Agent（Planner Agent）

输入：信息收集结果 + 用户偏好（预算、兴趣）
职责：生成按天划分的行程草案，每天包含上午 / 下午 / 晚上三个时段，每时段一个地点 + 预估开销
学习要点：Agent 如何消费上游 Agent 的结构化输出；如何约束输出格式（JSON Schema）

Agent 3：校验 Agent（Reviewer Agent）

输入：行程草案 + 预算
职责：检查两项规则
1. 总开销是否超预算
2. 行程是否存在明显不合理（时间冲突、天气不适宜户外活动）
输出：通过（pass）/ 失败（fail）+ 修改建议列表
学习要点 ：条件分支与循环 ------ 校验失败时，携带修改建议循环回规划 Agent 重新生成，最多重试 2 次；仍失败则输出失败原因

最终输出

校验通过后输出完整 JSON：目的地、每日行程、总预算、开销明细、备注
学习要点：结构化输出与序列化

1.3 非功能需求

所有 Agent 的执行过程必须可追踪：输入、输出、耗时、工具调用记录均写入日志（可观测性）
编排循环必须有硬性上限：总重试次数、单 Agent 最大迭代次数，防止死循环
全部工具可用 mock 实现（返回固定数据），不要求接真实 API

1.4 验收标准（可直接测试）

输入「杭州，2 天，预算 1500 元，喜欢美食和自然风光」，系统能在 3 次编排循环内产出合法 JSON
把预算改成 500 元（明显不够），系统能触发「规划 → 校验 → 再规划」循环，并给出合理调整（减少景点、换成免费活动）
把校验规则改成「开销必须为 0」（必失败），系统能在 2 次重试后优雅输出失败原因，而非死循环
任意一次运行，日志里能看到每个 Agent 的调用链

1.5 可选加分项（不强制）

人在环中（Human-in-the-loop）：最终输出前暂停，等用户确认或修改后再定稿
状态持久化：把中间状态保存下来，支持断点续跑

第二部分 V2：知识库驱动版（真正落地）

在 V1（三个 Agent 串行 + 循环校验）基础上，增加一个知识库层 作为所有 Agent 的数据来源。

与普通练习的区别：系统的所有信息都来自知识库（而非模型记忆或随意生成），且必须保证查询结果正确、可溯源。

2.1 系统整体架构（数据流）

复制代码

用户输入
  ↓
[路由 Agent] ------ 判断问题类型，分发到不同查询通道
  ├─→ 文本检索通道（向量库）      ← 景点介绍、历史文化类问题
  ├─→ 表格查询通道（Text2SQL）    ← 门票价格、开销计算类问题
  └─→ 混合通道（两者组合）        ← 需要多跳推理的复杂问题
  ↓
[信息收集 Agent] ------ 汇总检索结果，输出结构化信息包
  ↓
[规划 Agent] ------ 生成按天划分的行程草案（含每项开销）
  ↓
[校验 Agent] ------ 预算检查 + 事实核对 + 合理性检查
  ├─→ 通过 → 输出最终 JSON
  └─→ 失败 → 携带修改建议循环回规划 Agent（最多 2 次）

2.2 知识库设计（学习重点一：文件处理）

知识库包含三种刻意「有难度」的格式，全部用 mock 数据构建：

知识库内容	格式	设计难点	处理路线
景点资料	PDF / Markdown 文本	长短文档混合、专有名词密集	文档加载 → 切块 → 向量化检索
门票价格表	Excel（多 Sheet、合并单元格、多级表头、淡旺季列）	数值型、结构复杂，直接向量化必然出错	结构化还原 → 入库 → Text2SQL 查询
美食指南	半结构化文档 + CSV 价格区间表	文本与数值混合	混合检索：关键词 + 向量 + 表格路由

文件处理管线（入库流程，启动时执行一次）

你要能回答每一步「为什么这么做」。

步骤 1 · 格式解析：PDF 用解析库提取文本；Excel 用读取库逐 Sheet 读取，不丢格式信息
步骤 2 · 表格结构化还原（核心难点） ：
- 合并单元格逐格展开（每个被合并的行/列都补全值）
- 多级表头拍平（如「门票类型 → 成人/学生 × 季节 → 淡/旺」拆成规范扁平列）
- 转成标准行数据
步骤 3 · 双轨存储 ：
- 文本 → 切块（记录块大小 / 重叠率，便于后续调参）→ Embedding → 向量库
- 表格 → 结构化入库（数据库），同时将表格语义描述向量化，用于查询路由
步骤 4 · 更新机制：文档变更后支持重新入库，旧版本数据不再参与检索

2.3 查询正确性保障（学习重点二：落地分水岭）

这是「能不能落地」的关键。要求同时做到以下三件事。

① 问题路由 ：路由 Agent 先判断问题类型 ------ 文本检索 / 表格数值查询 / 多跳组合，不同类型走不同查询通道。这是正确性的第一道保障。
② Text2SQL 查询链（含护栏） ：
- 语法校验
- 表名 / 列名白名单校验
- 强制 LIMIT 上限
- 数值答案必须来自 SQL 执行结果，禁止 LLM 凭记忆输出 ← 表格查询正确性的核心原则
③ 引用溯源 + 事实校验 ：
- 任何答案必须附来源（文档名 / 页码，或表格名 / 行号 / 字段）
- 校验 Agent 复查答案中的数值是否与检索结果一致
- 知识库中不存在的信息，明确回答「知识库中无此信息」，禁止编造

2.4 Agent 角色划分

Agent	职责	框架概念对照
路由 Agent	判定问题类型，分发到正确通道	条件路由（Edge / Workflow 分支）
检索 Agent	向量 / 关键词检索，返回文本证据	工具调用（Tool / Toolkit）
表格查询 Agent	Text2SQL + 护栏执行，返回结构化数值	结构化输出约束
规划 Agent	基于信息包生成行程草案	消费上游结构化输出
校验 Agent	预算核对、事实核对、合理性检查	条件分支 + 循环（Checkpoint / Loop）

2.5 非功能需求

全流程可观测：每个 Agent 的输入、输出、耗时、工具调用记录均有日志
硬性上限：总重试次数 ≤ 2、单 Agent 最大迭代次数有界，防止死循环
工具可 mock：学习阶段全部工具返回固定数据，不接真实 API

2.6 验收标准（可直接逐项测试）

2.7 可选加分项（不强制）

人在环中（Human-in-the-loop）
状态持久化 / 断点续跑

第三部分框架概念对照表

照着实现时的「地图」------同一个需求要素在不同框架里的对应位置。

V1 核心概念

需求要素	LangGraph	Neuron AI	CrewAI
信息收集 / 规划 / 校验	三个 Node	三个 Agent / Workflow 步骤	三个 Agent（role + goal）
共享数据	类型化 State	消息 / 上下文传递	共享任务输出
校验失败重试	条件 Edge 构成循环图	工作流循环事件	任务依赖 + 重试
输出约束	Structured Output	Schema 约束	输出描述约束

V2 落地概念

学习点	LangGraph	Neuron AI	备注
文件处理管线	自定义 Node 链	内置数据加载器 + RAG 管线	Neuron 开箱即用程度更高
表格结构化	需自己写解析	部分内置	两者都要理解「为什么表格不能直接向量化」
查询正确性护栏	自建校验 Node	工具 + Schema 约束	核心是思路，不是框架
评估与溯源	LangSmith 可观测	Inspector 集成	建议同时建自己的测试集，不依赖平台

第四部分学习路径与验收总清单

4.1 四阶段学习顺序

第一阶段 · 纯编排：做 V1（不含知识库）------ 搞懂单 Agent 的 LLM 调用、工具定义、结构化输出、循环控制
第二阶段 · 知识库与文件处理：加入 V2 的知识库和文件处理管线 ------ 重点攻克复杂表格的结构化还原
第三阶段 · 正确性保障：加入路由 + Text2SQL 护栏 + 溯源 ------ 按 V2 验收标准逐项打勾
第四阶段 · 进阶（加分）：人在环中、状态持久化、断点续跑

4.2 难度阶梯（同一需求，三天版）

入门版（1 天）：只实现「信息收集 Agent + 规划 Agent」串行两步，先搞懂单 Agent 的 LLM 调用、工具定义、结构化输出。任何框架都可以
标准版（2--3 天）：完整实现 V1，重点攻克循环和条件分支------这是理解框架编排能力的分水岭
进阶版（选做）：V2 全量 + 状态持久化 + 人在环中，对比 LangGraph 的 Checkpoint 与 Neuron AI 的 Workflow 事件机制

4.3 最终收获清单

完成本手册后，你应当能交付：

V1 在至少 1 个框架上的可运行实现
V2 在至少 1 个框架上的可运行实现（含知识库 + 正确性保障）
一份「同一问题的 N 种解法」框架对比笔记
一份可复用的工程经验沉淀：
- 文档处理怎么设计（切块 / 重叠率 / 更新机制）
- 表格怎么不出错（结构化还原 + Text2SQL 护栏）
- 答案怎么可验证（溯源 + 事实校验 + 金标准测试集）

附录 A：建议的项目结构

复制代码

travel-agent/
├── data/                    # mock 知识库原始文件
│   ├── attractions.pdf      # 景点资料（文本类）
│   ├── tickets.xlsx         # 门票价格表（复杂表格类）
│   └── food_guide.csv       # 美食指南（半结构化类）
├── ingest/                  # 文件处理管线
│   ├── pdf_loader.*
│   ├── excel_normalizer.*   # ← 合并单元格展开 + 多级表头拍平
│   └── vector_store.*
├── agents/                  # Agent 定义
│   ├── router_agent.*
│   ├── search_agent.*
│   ├── sql_agent.*          # ← 含护栏
│   ├── planner_agent.*
│   └── reviewer_agent.*
├── tools/                   # 工具（mock 实现）
├── tests/
│   └── golden_set.*         # 10 道金标准测试题
└── logs/                    # 可观测性日志

Agent 框架新手入门与实战部署指南

Agent 框架学习需求手册

目录

0. 如何使用本手册

第一部分 V1：纯编排版（先跑通 Agent 编排）

1.1 项目背景

1.2 功能需求

Agent 1：信息收集 Agent（Search Agent）

Agent 2：规划 Agent（Planner Agent）

Agent 3：校验 Agent（Reviewer Agent）

最终输出

1.3 非功能需求

1.4 验收标准（可直接测试）

1.5 可选加分项（不强制）

第二部分 V2：知识库驱动版（真正落地）

2.1 系统整体架构（数据流）

2.2 知识库设计（学习重点一：文件处理）

文件处理管线（入库流程，启动时执行一次）

2.3 查询正确性保障（学习重点二：落地分水岭）

2.4 Agent 角色划分

2.5 非功能需求

2.6 验收标准（可直接逐项测试）

2.7 可选加分项（不强制）

第三部分 框架概念对照表

V1 核心概念

V2 落地概念

第四部分 学习路径与验收总清单

4.1 四阶段学习顺序

4.2 难度阶梯（同一需求，三天版）

4.3 最终收获清单

附录 A：建议的项目结构

第三部分框架概念对照表

第四部分学习路径与验收总清单