为什么 Google ADK 是最好的 Agent 框架 —— 全书大纲

关于这本书

这是一本实战教程书。它不满足于告诉你 ADK 有哪些 API，而是带着你从零搭一个真实的生产级 Agent 系统，并在每一步讲清楚"为什么 ADK 要这样设计"。

这本书的读者是：有 Python 基础、想从零搭建 Agent 系统的工程师。读完这本书，你不仅能熟练使用 ADK，还能理解现代 Agent 框架背后的一整套设计取舍——这比记住任何 API 都值钱。

一句话论点

纯 Agent（让 LLM 自己编排一切）在生产环境会死于成本、失控和难调试。Google ADK 2.0 用"图工作流引擎 + 确定性路由 + 多语言 + 开放协议"，把"智能的推理"和"可靠的逻辑"分开——这才是 Agent 框架该有的样子。

贯穿全书的主线项目

一本教程书最好的老师，是一个从头长到尾的真实项目。本书的项目是：

「云销」智能客服 + 工单处理系统（一个电商售后退货场景）

• 第 2 章：它只是一个能查订单、查退款政策的单 Agent
• 第 4 章：变成订单/退款/物流三个子 Agent 的客服团队
• 第 5 章：用图工作流重写退货审批流程
• 第 6 章：加入"人工审核退款"的人机协作节点
• 第 8 章：部署到自有服务器 / Cloud Run 等任意环境
• 第 10 章：加上评估集，量化客服质量
• 第 11 章：加上安全防护（退款必须人工审批）
• 第 12 章：完整复盘，从 v0.1 到生产级

你跟着每一章改代码，项目一点点长大。这是教程书最有效的组织方式。

---

全书结构（13 章 + 2 附录）

第一部分：起步（第 1-3 章）—— 先搞清楚为什么，再动手

第 1 章 Agent 框架版图：2026 年该选谁

• 为什么突然冒出来这么多 Agent 框架
• 八个框架逐一速览与定位（均附 GitHub repo）：
  • LangChain / LangGraph：生态最全的"全家桶"（github.com/langchain-ai/langchain · langgraph）
  • Microsoft Agent Framework：微软的 Agent 运行时与编排（github.com/microsoft/agent-framework）
  • CrewAI：角色扮演式多智能体的开山之作（github.com/crewAIInc/crewAI）
  • deepagents：LangChain 系"深度推理"派（github.com/langchain-ai/deepagents）
  • Claude Agent SDK：Anthropic 的官方智能体框架（github.com/anthropics/claude-agent-sdk-typescript）
  • AgentScope：阿里达摩院的多智能体分布式框架（github.com/agentscope-ai/agentscope）
  • OpenAI Agents：OpenAI 官方，极简轻量（github.com/openai/openai-agents-python）
  • Google ADK：Google 官方，生产优先（github.com/google/adk-python）
• 评估框架的五个维度：可控性、可观测性、多智能体、生态连接、生产路径
• 用五维雷达图横向对比八个框架
• 为什么这本书选 ADK：不是因为它功能最多，而是它的设计取舍最接近生产真相

第 2 章 30 分钟搭第一个 Agent

• 安装与准备：pip install google-adk、模型 API Key 配置（Gemini 或 OpenAI / Anthropic / Ollama 均可，不强制 Google）
• Agent 是一个 Python 对象：Agent(model=, tools=, instruction=)
• 代码优先的体验：可调试、可测试、可版本控制
• 三种运行方式：CLI、Web UI、API Server
• 主线项目启动：云销客服 v0.1（能查订单、查退款政策）
• 「为什么 ADK 这样设计」：代码优先 vs 声明式配置

第 3 章 工具与上下文：Agent 的能力来源

• 工具 = Python 函数：函数工具、MCP 工具、OpenAPI 工具
• 技能（Skills）入门：什么是 Skill（自包含的功能单元：指令 + 资源 + 工具）、如何加载并挂载到 Agent、一个最小示例
• Session 与状态：多轮对话怎么记住
• 事件流模型：每个决策可追踪
• 记忆、压缩、缓存：上下文管理的完整方案
• 「为什么 ADK 这样设计」：结构化上下文 vs 把一切塞进 prompt

第二部分：多智能体与工作流（第 4-7 章）—— 本书核心

第 4 章 多智能体协作：从单兵到团队

• 协作模式：Coordinator + 子智能体
• 主线项目：客服 v1.0 → 订单/退款/物流三 Agent 团队
• 顺序、并行、路由三种协作语义
• 什么时候该用多智能体，什么时候不该（过度拆分是反模式）
• 「为什么 ADK 这样设计」：Agent 通信 vs 直接调函数

第 5 章 图工作流：ADK 2.0 的核心武器

• 为什么 ADK 从"Agent-Centric"重写为"Graph-Based"
• 节点即一切：Agent、工具、函数都是图上的节点
• 确定性路由 vs LLM 自由编排
• 动手：用图工作流重写退货审批流程
• 「为什么 ADK 这样设计」：成本（3-5 倍）、可控性、防循环

第 6 章 动态工作流与人机协作

• 动态分支：迭代循环、复杂条件决策
• HITL（Human-in-the-loop）：工作流暂停、等待人工、恢复
• 自动重试与遥测：RetryConfig
• 主线项目：退货流程加入"人工审核退款"节点
• 「为什么 ADK 这样设计」：把 if-else 还给代码，把判断留给 LLM

第 7 章 模型中立、开放生态与协议标准

• 不绑 Google：模型、工具、部署全链路的中立设计
  • 模型中立：一个框架跑所有模型——Gemini、Claude、OpenAI、Ollama、vLLM、LiteLLM
  • 工具中立：函数工具 + MCP + OpenAPI，不依赖 Google 工具
  • 部署中立：自有服务器 / Docker / Cloud Run / GKE / Vertex AI 随你选
  • 动手：把客服 Agent 从 Gemini 切到 Claude / Ollama，代码零改动；部署到非 Google 环境
• 技能（Skills）深入：可复用的能力包
  • 三层结构：L1 元数据 / L2 指令 / L3 资源（references · assets · scripts）
  • 从文件系统加载 vs 代码内联定义
  • 与 Agent Skill 规范（agentskills.io）的关系
  • 集成使用：在单 Agent、多 Agent 协作、图工作流节点中挂载技能
  • 主线项目：给云销客服封装"订单查询技能"和"退款政策技能"
• Agent 开源协议标准全景
  • MCP：工具层协议，Agent 接入任意工具生态
  • A2A：Agent 与 Agent 通信协议
  • AG-UI（Agent-User Interaction）：把 Agent 带进前端界面的交互协议
  • AGENTS.md：给编码 Agent 看的项目说明文件，跨工具通用的开放格式
  • 其他：Agent Protocol（任务执行标准化）、agentskills.io
  • 一张图：这些协议分层协作的关系（工具层 / Agent 间 / 人机界面 / 项目上下文）

第三部分：生产落地（第 8-12 章）—— 最好的框架要能上生产

第 8 章 部署：从本地到云端

• Agents CLI 一键启动、Web UI、可视化构建器
• 部署路径：自有服务器 / Docker / Cloud Run / GKE / Vertex AI Agent Engine（不强制 Google，全看你需求）
• 非 Google 环境部署实操：Docker 容器化 + 自有服务器 / 任意云（AWS、阿里云等）
• 多语言生产：Python / TypeScript / Go 同步 GA
• 主线项目：云销客服容器化，部署到自有服务器 + 可选云平台

第 9 章 可观测性：Agent 不是黑盒

• 为什么 Agent 比传统服务更难观测：LLM 的不确定性 + 工具调用的副作用 + 多步决策链
• 观测的三根支柱：日志（Logs）、指标（Metrics）、追踪（Traces）
  • 结构化日志：谁调用了什么工具、模型返回了什么、耗时多少
  • 关键指标：单次请求的 LLM 调用次数、工具调用次数、token 消耗、延迟、成功率、循环检测
  • 分布式追踪：一次用户请求跨多个 Agent / 工具的完整链路
• ADK 的事件流是观测的基础：每个决策都留下结构化痕迹
  • 事件类型：模型调用、工具调用、Agent 切换、人工介入、错误
  • 如何把事件流接入外部观测系统（OpenTelemetry 等）
• 用事件流做调试实战：定位一次"客服答错"的根因
  • 从现象到根因的排查路径：是模型幻觉、工具数据错误、还是路由决策错了？
  • 复现与回放：把一条事件流重放一遍，验证修复
• 主线项目：给云销客服加日志、指标面板和追踪
• 与第 1 章"黑盒问题"首尾呼应：可观测性是生产 Agent 的入场券

第 10 章 评估：让 Agent 质量可量化

• 为什么评估是 Agent 框架的分水岭：模型输出不确定，测试必须自动化
• 评估的四个层次
  • 单步评估：每次工具调用 / 模型响应是否正确（单元测试粒度）
  • 场景评估：完整对话 / 任务跑一遍，结果是否符合预期（集成测试粒度）
  • 用户模拟：模拟真实用户行为（正常流程 + 刁钻边界 + 恶意输入）
  • 环境模拟：模拟外部依赖（工具故障、超时、模型降级）下 Agent 的表现
• 评估指标怎么设计：正确率、任务完成率、工具调用准确率、HITL 介入率、成本
• 自定义指标与评估优化：如何迭代 prompt / 工具 / 工作流让分数上升
• 评估与开发流程的结合：评估集成为 CI 的一环，每次改动自动跑回归
• 主线项目：给云销客服建一套评估集（正常订单查询、退货审批、边界刁难问题）

第 11 章 安全：Agent 的护城河

• 为什么 Agent 是新的攻击面：LLM 既是执行者又是被攻击目标
• 安全威胁全景
  • 提示词注入：恶意指令藏在用户输入 / 工具返回里
  • 数据泄露：Agent 把不该说的内部信息说出去
  • 过度授权：Agent 调用工具的权限边界
  • 工具滥用 / 越权操作：Agent 被诱导做危险动作
• 防护手段
  • 输入侧：注入检测、上下文隔离、权限最小化
  • 输出侧：敏感信息过滤、输出合规校验
  • 机制侧：HITL 人工审批关键操作、工具调用白名单、审计日志
• ADK 内置的安全能力与推荐实践
• 主线项目：给云销客服加安全防护（退款这类敏感操作必须人工审批）
• 安全与第 6 章 HITL 呼应：人机协作不只是体验，更是安全闸门

第 12 章 真实项目复盘与边界

• 完整复盘：从 v0.1 到生产级客服系统（架构图 + 代码回顾）
• 诚实的边界讨论：什么时候不该用 ADK、迁移成本、社区生态
• 为什么这本书叫"为什么最好"：ADK 的选择与替代方案对比

第四部分：收尾

第 13 章 总结与进阶路线

• 全书知识地图
• 进阶方向：Agent Config、REST API、在线/语音智能体
• Agents CLI 辅助开发（vibe coding）：把 ADK 官方技能注入 Claude Code / Cursor / Antigravity 等 AI 编程助手，让 AI 帮你搭项目、写 Agent、做评估、部署上云
• 行动清单：读完这本书你应该能独立搭建什么

附录 A：ADK 2.0 五语言速查（Python / TypeScript / Go / Java / Kotlin 最小示例）

附录 B：adk.wiki 中文文档地图（wiki 章节 → 本书章节映射，方便深读）

---

写作规范

• 格式：Markdown，中文，frontmatter 与现有博客体系一致（title/date/tags/description）
• 每章结构：
  • 章节引言（一个真实场景故事）
  • 动手部分（可运行代码 + 截图/输出）
  • 「为什么 ADK 这样设计」解读框
  • 本章小结 + 练习
• 代码：每章代码在本地真实跑通（pip install google-adk + 主线项目），确保可复现
• 长度：每章 5000-8000 字，全书 8-10 万字
• 不复制：不照搬已有博客文章，不翻译官方文档，全部基于主线项目原创

写作顺序

教程书的写作顺序与阅读顺序一致，但分批推进：

1. 第一批（打基础）：第 1、2、3 章 —— 让读者最快获得"我能搭 Agent"的正反馈
2. 第二批（核心）：第 4、5、6 章 —— 多智能体 + 图工作流，本书最独特的部分
3. 第三批（生产）：第 7、8、9、10、11 章 —— 生态协议、部署、观测、评估、安全
4. 第四批（收尾）：第 12、13 章 + 附录

发布计划

• 全书完成后，以 books/ 菜单发布到 Svelte Web
• 章节文件命名：adk-ch01.md、adk-ch02.md ...（沿用 blogs.js 已有的 -chXX.md 章节排序机制）