第 12 章 真实项目复盘与边界
第 12 章 真实项目复盘与边界
从第 2 章的 v0.1 到现在的生产级系统，云销客服走过了十章的进化。这一章，我们停下来做一次完整的复盘——看架构怎么一步步长成、每个关键决策背后的权衡、踩过哪些坑。然后，聊一个诚实的话题：ADK 的边界在哪里，什么时候不该用它。
12.1 云销客服的完整演进
12.1.1 版本时间线
让我们回顾云销客服的每一次进化：
| 版本 | 章节 | 关键变化 | 架构形态 |
|---|---|---|---|
| v0.1 | 第 2 章 | 单 Agent，能查订单/退款政策 | 单体 Agent + 2 个函数工具 |
| v0.2 | 第 3 章 | 加 State 记忆，支持多轮对话 | 单体 Agent + 有状态工具 |
| v1.0 | 第 4 章 | 拆成订单/退款/物流三 Agent 团队 | 协调者 + 3 个子 Agent |
| v2.0 | 第 5 章 | 图工作流重写退货审批 | 图工作流（确定性流程） |
| v3.0 | 第 6 章 | 加入人工审批退款节点 | 动态工作流 + HITL |
| v4.0 | 第 7 章 | 封装技能、接协议生态 | Skills + MCP/A2A |
| v5.0 | 第 8 章 | 容器化部署 | Docker + 任意云 |
| v6.0 | 第 9-11 章 | 可观测性 + 评估 + 安全 | 生产级完整系统 |
12.1.2 最终架构图
┌─────────────────────────────┐
│ API Server │
│ (adk api_server / FastAPI)│
└─────────────┬───────────────┘
│ REST / SSE
▼
┌─────────────────────────────┐
│ yunxiao_cs (root) │
│ 协调者 Agent │
└─────────────┬───────────────┘
┌───────────────────────┼───────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
│ order_agent │ │ refund_agent │ │ logistics │
│ 订单查询 │ │ 退款处理(Skill) │ │ 物流查询 │
└──────┬───────┘ └────────┬─────────┘ └──────────────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────────┐
│ get_order │ │ 退货审批工作流 │
│ _status(工具) │ │ (Graph Workflow) │
└──────────────┘ │ + HITL 人工审批 │
└──────────────────┘
│
┌───────┴───────┐
│ │
▼ ▼
┌────────────┐ ┌────────────┐
│ approved │ │ rejected │
│ 自动退款 │ │ 告知用户 │
└────────────┘ └────────────┘
横切能力：Skills（退款技能）| MCP（外部工具）| A2A（远程 Agent）
可观测性（日志/指标/追踪）| 评估（EvalSet）| 安全（确认/回调）12.2 关键决策复盘
12.2.1 决策一：单体 → 多 Agent 的时机
问题：什么时候该把单体 Agent 拆成多 Agent？
我们的判断：当三个信号同时出现时拆——
- 指令开始冲突：查订单、退款、物流的规则互相打架
- 职责边界天然清晰：订单/退款/物流本来就是三个领域
- 需要独立迭代：退款流程经常改，其他很少变
教训：不要过早拆分。v0.1-v0.2 阶段单 Agent 完全够用，拆早了反而增加"该转给谁"的决策开销。
12.2.2 决策二：什么时候上 Graph Workflow
问题：多 Agent 协作已经能处理退货了，为什么还要图工作流？
我们的判断：当流程有确定的顺序和分支、且不能容忍 LLM 自由发挥时，必须用图工作流。退货审批的资格判断（查订单、比对日期）是确定性逻辑，用纯 Agent 会浪费 3-5 倍 token 且可能出错。
关键认知：多 Agent 处理"模糊分发"（该把任务给谁），图工作流处理"确定流程"（顺序/分支）。两者互补，不是替代。
12.2.3 决策三：HITL 的引入
问题：为什么退款要人工审批？
我们的判断：合规和安全需求。大额退款不能让模型自动放行——这是第 6 章和第 11 章反复强调的"代码强制"：把"超过阈值必须人工"固化在工作流/工具里，模型绕不过去。
12.2.4 决策四：部署路径
问题：部署到哪？
我们的判断：先用 adk api_server 本地跑通 → Docker 容器化 → 部署到自有服务器（非 Google 环境）。这套路径不依赖任何云厂商，是"部署中立"的实践。
12.3 踩过的坑
12.3.1 模型层
- Ollama 用
ollama前缀导致无限循环：必须用ollama_chat（第 7 章） - LiteLlm 的 import 路径：是
google.adk.models.lite_llm，不是litellm - 区域端点下
gemini-flash-latest选择器不生效：要用具体版本字符串
12.3.2 工作流层
- task 模式在 v2.0.0 的图工作流中被禁用：图里要用协作模式要留意版本
- 动态工作流里调用
ctx.run_node的节点必须rerun_on_resume=True：否则恢复时会出错
12.3.3 部署层
- 不配置 session_service_uri 导致会话丢失：生产必须持久化
- GKE 的 SQLite read-only：构建前要排除 sessions.db
12.3.4 安全层
- session state 存敏感凭据：官方明确警告不要这么做
- UI 不转义模型内容导致间接注入：必须转义
12.4 诚实的边界讨论
这一节是全书最"反广告"的部分。ADK 很好，但它不是万能的。
12.4.1 什么时候不该用 ADK
第一，你的项目只需要极简的 Agent 调用。
如果只是"调用一次 LLM 拿个 JSON"，ADK 是杀鸡用牛刀。直接用模型 SDK 或 OpenAI Agents 这种极简框架更合适。
第二，你的团队没有工程化基础。
ADK 的能力集中在"生产级"，但生产级需要配套的工程能力：可观测性后端、评估数据集、CI 流程。小团队如果没有这些，ADK 的很多能力用不上，反而觉得复杂。
第三，深度绑定特定生态的封闭场景。
如果你确定只用一个厂商的模型和云，且永远不会换，那么那个厂商的一站式框架可能更顺手。ADK 的中立性在你需要"自由"时才体现价值。
第四，极度简单的线性任务。
一个 Agent + 两个工具能解决的事，没必要上多 Agent + 图工作流。记住第 4 章的反模式：为拆而拆是灾难。
12.4.2 ADK 的短板（诚实清单）
- 社区和生态仍在追赶：LangChain 的第三方集成数量仍远超 ADK（第 1 章提过）
- 2.0 较新，迁移有成本：从 1.x 迁移有破坏性变更（自定义执行覆写、事件 append 等）
- 部分功能标注 experimental：模型路由、Visual Builder、环境模拟等仍是实验特性，API 可能变
- 中文资料相对少：官方文档英文为主（中文镜像 adk.wiki 在完善中）
- 技能生态刚开始：Skills 规范（agentskills.io）还在早期
12.4.3 什么时候 ADK 的优势最明显
反过来，ADK 优势最明显的场景：
- 企业级 Agent 系统：需要可控性、可观测性、评估、安全
- 多 Agent + 复杂工作流：混合编排是它的主场
- 不被绑定的需求：模型、部署都要自由选择
- 多语言团队：Python/TS/Go/Java/Kotlin 全支持
12.5 为什么这本书叫"为什么最好"
最后一节，我们回到书名。为什么我们有底气说"Google ADK 是最好的 Agent 框架"？
不是因为它功能最多（生态不如 LangChain）、不是因为它最简单（不如 OpenAI Agents）、不是因为它生态最封闭（它最开放）。是因为它的设计取舍，在 2026 年的生产环境下最正确：
- 图工作流引擎：把确定性逻辑从 LLM 手里夺回来——这是对 Agent 本质最深刻的理解
- 生产优先：可观测、可评估、可部署、可安全——一整套生产底座，不是后加的补丁
- 开放协议：模型中立、MCP、A2A——赌开放赢，不赌绑定赢
- 多语言同步：不被语言绑死
- 代码优先：可调试、可测试、无黑魔法
"最好"不是一个绝对判断，而是一个场景判断。在"构建生产级、复杂、不被绑定的 Agent 系统"这个场景下，ADK 是目前最接近正确答案的选择。这就是全书想传达的。
本章小结
- 云销客服十章演进：单体 → 多 Agent → 图工作流 → HITL → 生产级，每一步都有明确动机
- 四个关键决策：何时拆多 Agent、何时上图、为何上 HITL、部署到哪
- 踩坑清单：模型（ollama_chat/lite_llm）、工作流（rerun_on_resume）、部署（持久化）、安全（凭据）
- 诚实边界：极简场景、无工程化基础、封闭生态、简单线性任务——不该用 ADK
- 短板清单：社区追赶中、2.0 迁移成本、部分实验特性、中文资料少
- "最好"是场景判断：在生产级复杂 Agent 系统场景下，ADK 最接近正确答案
练习
- 复盘你的项目：如果你在搭 Agent 系统，按云销的演进路径（单体→多Agent→工作流→生产化）画一条你自己的路线图。
- 写边界文档：给你的团队写一份"什么情况用 ADK、什么情况不用"的决策文档。
- 成本估算：估算你的 Agent 系统如果分别用"纯 Agent"和"图工作流混合"的成本差异。
下一章预告：第 13 章，全书收尾。我们把所有知识串成一张地图，然后看 ADK 的进阶方向——Agents CLI 辅助开发、Visual Builder、REST API、在线语音 Agent。