端到端实战：从 0 到 1 搭一个生产 Agent
前面 10 篇讲的都是「零件」和「原则」——现在要做的，是把它们装成一台能上线的机器。
这一篇不教你新概念，而是带你走一遍完整闭环：需求 → 选型 → 实现 → 评估 → 护栏 → 上线。 为什么要有这一篇？因为「零件都会了」和「能装出能跑的机器」之间，隔着一条真实的鸿沟——整合的鸿沟。前面每篇是「怎么用这个零件」，这一篇是「怎么把这些零件装在一起，还不出错」。
1. 把零件装成机器：整合的难点在哪
先说清楚，为什么「整合」是一道独立的坎。前面 10 篇各自独立时，每个零件都「看起来懂了」；但一旦要装成一台机器，会同时暴露三个新问题：
- 零件之间的衔接：RAG 检索到的内容，怎么传给 Function Calling 的工具？Trace 怎么覆盖「检索 + 调用 + 生成」全链路？这些边界，单篇里都不会讲。
- 「够用」的克制：每个零件都有「加不加」的选择，而整合时最难的，恰恰是判断「这个场景不需要加」——用多了是过度设计，用少了是隐患。
- 上线门槛：零件阶段「跑通就行」，上线阶段「每一步都得可回溯、可兜底、可止损」——这是完全不同的标准。
这一篇的价值，就是带你走一遍这些衔接和权衡，让你对整个系列有一个「串起来」的通透感。
打个比方：前面学了怎么选螺丝、怎么拧扳手，现在要真正组装一台机器，并确认它能安全运转。学到的每一个零件，都要在这里「上机验证」。
2. 选一个能串起全部知识点的场景
2.1 场景：企业内部的「智能知识问答 Agent」
我们选一个能串起最多知识点的场景：企业内部知识库问答。
选它的理由：一个看似简单的问题「帮我查一下公司最新的报销政策」，背后要调动的东西几乎覆盖全篇——检索（03）、工具调用（04）、记忆（08）、评估（09）、护栏（10）。一个场景串起五篇，性价比最高。
2.2 架构选型（用 07 的决策）
这是「整合」的第一个权衡点。先看这个任务的特征：
- 步骤相对明确（查 → 组织 → 答）；
- 不需要多角色并行协作（就是「问 → 查 → 答」一条线）。
所以结论很清晰：不上 Multi-Agent（那是过度设计），而是用 单 Agent（ReAct）＋ 一个 RAG 检索工具，足够且可控。
记住 07 的口诀：能用个体户，就别开公司。 整合的第一课，就是「克制」——不是零件越多越高级，而是「刚好够用」最专业。
3. 一步步搭出来
下面六步，每一步都对应前文的一个或几个零件，我会明确标出引用的篇章和「为什么这一步只做这些」。
3.1 第 1 步：定需求与边界（10 的前置）
先把「它到底要干什么」钉死，越窄越好：
- 只做：根据内部知识库回答员工问题，并给出引用来源。
- 不做：不答知识库之外的事（避免它瞎编）；不执行任何写操作。
这个「只做 / 不做」的清单，就是后面「权限最小化」的依据。 别忘了 10 篇的重要原则：安全不是事后补的，是需求阶段就定死的。 现在把边界划清楚，后面的护栏就是水到渠成，而不是亡羊补牢。
3.2 第 2 步：搭骨架（03 + 04）
先做最小闭环：一条「问题 → 检索 → 回答」的通路。
# 最小可用 Agent：只给一个只读检索工具（权限最小化）
tools = [检索知识库] # 只读，无写/删除
agent = ReAct(模型, tools) # 单 Agent 循环（04 篇）
回答 = agent.run("公司最新的报销政策是什么？")这一步只验证「能查、能答」，不追求完美。关键决策：只给一个「检索」工具，且是只读的。 这既是 03 篇（RAG 检索）的落地，也是 10 篇（权限最小化）的第一道闸。
3.3 第 3 步：接入持久化 + 可观测（07 + 09）
- 给「检索并生成回答」的过程接检查点（checkpoint），让它能断点续跑、能追踪（07 篇）；
- 接 Trace，每一次运行都留下轨迹（09 篇）。
为什么这里不上「人工确认」？ 因为这个 Agent 只有只读、无副作用——它不会改数据、不会花钱，所以不需要人工把关。安全靠「根本不给写权限」就实现了（10 篇的权限最小化），而不是靠「关键动作前设关卡」。
这里体现一个重要的判断力：Human-in-the-loop 不是每个 Agent 都要的，只在「有不可逆副作用」时才需要。 一个只读的问答 Agent，硬加人工确认反而是画蛇添足。护栏的「剂量」，要根据「破坏能力」来配。
3.4 第 4 步：加记忆（08）
给 Agent 加一层短期记忆：记住用户在这次会话里追问的上下文（「刚才说的那个政策，适用新员工吗？」）。
但暂时不上长期记忆——为什么？因为知识库本身就是「长期知识」：公司的政策、流程，都已经存在向量库里了。用户跨会话「上次我问过报销」这种个人长期偏好，在这个纯知识问答场景里价值不大，重复堆长期记忆反而冗余。
判断标准（这是整合的核心能力）：别为了「用上某个技术」而用它，只在「确实解决痛点」时才加。 08 篇讲的「记忆要提炼、召回、淘汰」，在这个场景里，知识库已经承担了「长期」的角色，Memory 只补「会话内短期」这一小块即可。
3.5 第 5 步：评估 + 可观测（09，上线前关键一步）
这是上线前的关键一步，也是「demo」和「生产」的分水岭（呼应 07、09 篇的「分水岭」主题）：
- 建一个 50 条的小评测集：覆盖高频问题 + 边界问题（「问知识库外的问题」「问敏感数据」）。
- 接 Trace：每一次运行都留下轨迹，能回溯「它是怎么查到答案的」。
- 跑评测 + 看指标：成功率、引用准确率、平均步数、单次成本。
这一关过了，才谈得上线。 具体到 RAG，尤其要盯「引用准确率」——因为一个「答对了但引用错了出处」的答案，在严肃场景里是不可信的（03 篇的引用回链）。
3.6 第 6 步：上线清单
上线前逐条打勾，每一条都能回溯到前文的某个「命门」：
- [ ] 检索工具是只读的，无任何写/删除权限（10 权限最小化）
- [ ] 外部知识库内容按不可信数据对待，关键动作有白名单（10 防注入）
- [ ] 接入了检查点 + Trace，能断点续跑、能回溯（09 可观测）
- [ ] 有评测集，且上线前跑通了（09 评估）
- [ ] 设了成本上限（防烧钱）+ 失败兜底（查不到时明确说「查不到」，而非瞎编）
最后一条「失败兜底」值得单独强调：RAG 最怕的就是「查不到却硬编」。 一定要让 Agent 在检索无果时，明确回答「抱歉，知识库里没有相关资料」，而不是让模型「自以为知道」地编一个——这既是 03 篇的「溯源」要求，也是最常见的生产事故源头。
4. 复盘对照表：把 01–10 的命门逐条打勾
这张表，是整个系列的一份「索引」。它把每一篇的核心知识点，都映射到「在本例中怎么落地」，帮你验证「到底学会了没有」：
| 篇 | 知识点 | 在本例中怎么落地 |
|---|---|---|
| 02 提示词 | 清晰的 system 约束「只答知识库内的」 | ✅ 需求边界里写死 |
| 03 RAG | 检索 + 引用回链 | ✅ 检索工具 + 给来源 |
| 04 FC/Agent | 单 Agent 循环调工具 | ✅ ReAct 骨架 |
| 05 框架 | 用 LangGraph 编排 | ✅ 节点/边/检查点 |
| 06 MCP | 工具能否生态复用来接入 | 🔶 检索工具可封装成 MCP Server 供其它 Agent 复用 |
| 07 编排 | 单 Agent 够用，不上多 Agent | ✅ 架构选型 |
| 08 记忆 | 短期记忆够用，不上长期 | ✅ 克制 |
| 09 评估 | 评测集 + Trace + 指标 | ✅ 上线门槛 |
| 10 护栏 | 只读权限 + 防注入 + 成本上限 | ✅ 上线清单 |
🔶 表示「可选优化」：当前不阻塞上线，但日后若想让这个检索能力被其它 Agent 复用，可把它封装成 MCP Server（呼应 06 篇「写一次、处处可用」）。
这张表的意义，不只在于「本例」。你可以把它当成一个「checklist 模板」——以后你每搭一个 Agent，都可以拿这张表过一遍，问自己「这 10 个维度，我考虑全了吗」。你会发现，「漏掉某一篇的命门」，正是大多数 Agent 项目失败的常见原因。
5. 记住这一句
搭 Agent 不是堆零件，是「先跑通最小闭环 → 再按需加记忆/护栏 → 最后用评测集把关才上线」。每个零件只在「真的解决痛点」时才加，加得越多，越要记得它带来的新风险。
全文结束。 从 01 到 11，你走完了一条完整路线：先建立「Agent 是什么」的心智模型，再逐层拼上「会对话、懂数据、会行动、会落地、会协作、长记性、可度量、守边界」，最后亲手组装出一台能上线的机器。
接下来，剩下的就是把每一篇读深，把每一个「命门」变成你能随时复述的红线——因为真正的功力，不在「知道这些概念」，而在「能在关键时刻想起并守住这些红线」。