1. 为什么这份手册值得逐页拆解Google 发布的《AI Agent Handbook》在圈内流传开来之后我第一时间通读了两遍。第一遍是当作产品介绍看的第二遍是带着如果我要在企业里落地一套 Agent 系统这份手册能给我什么的问题去读的。结论很直接它不是一份教你写 Prompt 的入门读物而是一份站在平台方视角、把企业级 Agent 从底层能力到上层产品全部串起来的架构说明书。很多人对 AI Agent 的理解还停留在给大模型加个工具调用的阶段觉得能查天气、能算数学题就算 Agent 了。这种认知在个人练手项目里没问题但一旦放到企业场景立刻会撞上几堵墙权限怎么管、多个 Agent 之间怎么协作、状态怎么持久化、成本怎么控制、出了问题怎么排查。这份手册的价值就在于它把这些墙提前标了出来并且给出了 Google 自己的解法。我写这篇拆解的目的很明确把手册里那套六层架构讲透把每一层对应的产品矩阵理清楚再补上我在实际搭建 Agent 时踩过的坑和验证过的做法。不管你是刚接触 Agent 开发的新手还是已经在做企业级中台的工程师都能从里面找到能直接抄作业的部分。核心关键词就几个Google、AI Agent、Agent2Agent、Vertex AI、no-code这几个词基本覆盖了从协议层到应用层的全部关键点。需要先说明一点手册本身是 Google 的官方材料但我在解读时会加入大量基于常见工程实践的补充和推演凡是手册没写死、但实际落地必须考虑的地方我都会明确标注出来。这样你读到的不是一份翻译而是一份带注释的实战笔记。2. 六层架构的整体设计思路拆解2.1 为什么是六层而不是三层或五层先解决一个很多人会忽略的问题为什么 Google 要把 Agent 架构切成六层三层不够用吗我一开始也觉得分层是种架构师的自我感动直到自己动手搭了一套多 Agent 系统才发现分层不是为了好看是为了隔离变化。Agent 系统里变化最快的是模型能力变化最慢的是底层基础设施如果把它们揉在一起每次模型升级都要动全身。六层架构的本质是把会变的东西和不变的东西用清晰的边界隔开。具体来说这六层从下往上大致是这样一条链路基础设施层 → 模型层 → 工具与数据层 → 编排层 → 协作层 → 应用层。每一层只依赖它下面那一层暴露出来的接口不关心下面怎么实现。这个设计思路和传统后端的分层架构是一脉相承的只不过把业务逻辑换成了Agent 的推理与行动。我特别想强调编排层和协作层被单独拆开这件事。很多自研 Agent 框架把这两件事混在一起做结果就是单个 Agent 跑得挺好一旦要多个 Agent 配合就乱套。Google 把它们分开编排层管的是一个 Agent 内部怎么规划任务、调用工具、维护记忆协作层管的是多个 Agent 之间怎么通信、怎么分工、怎么传递上下文。这个切分非常关键后面讲 Agent2Agent 协议时会再展开。2.2 每一层的职责边界与选型考量把六层摊开来看每一层的职责其实可以用一句话概括但背后的选型考量值得细说。基础设施层负责算力、存储、网络这些最底层的东西。企业场景下这一层通常不是自己搭而是用云服务。选型时最该关注的不是哪家便宜而是能不能和上层模型服务无缝对接。Google 在这里的答案是 Vertex AI 背后的那套基础设施好处是模型、工具、编排全在同一朵云里网络延迟和权限打通都省事。模型层就是各种大模型包括通用模型和针对特定任务微调过的模型。这里有个常见误区很多人以为企业级 Agent 一定要用最大的模型。实际上不是手册里隐含的思路是按任务选模型——规划用强模型执行简单工具调用用轻量模型这样成本和延迟都能压下来。工具与数据层是 Agent 的手脚和记忆。工具包括各种 API、数据库查询、代码执行环境数据包括向量库、知识图谱、业务数据库。这一层最容易出问题的地方是权限Agent 能调用的工具必须和它被授予的权限严格对应否则一个越权调用就可能造成事故。编排层是单个 Agent 的大脑皮层负责把用户请求拆成子任务、决定调用哪个工具、处理工具返回结果、维护对话状态。这一层的核心难点是状态管理长对话、多轮工具调用之后上下文会变得非常长怎么压缩、怎么取舍直接决定 Agent 好不好用。协作层是多个 Agent 之间的社交规则。谁负责规划、谁负责执行、谁负责审核任务怎么分发、结果怎么汇总都在这一层定义。Agent2Agent 协议就是为这一层服务的。应用层是最终用户看到的东西可能是聊天界面、可能是嵌入到现有系统里的自动化流程、也可能是 no-code 平台上的可视化编排。这一层的设计原则是隐藏复杂度用户不需要知道下面有几层只需要把事办成。2.3 分层带来的三个实际好处讲完职责说说分层在实际项目里到底带来了什么。我自己感受最深的有三点。第一是可替换性。模型层换了模型只要接口不变上面几层几乎不用动。我做过一次实验把编排层里调用的模型从一个大模型换成另一个只改了一行配置整个 Agent 的行为逻辑完全不受影响。这在没有分层的系统里是不可想象的。第二是可观测性。分层之后每一层都可以单独打日志、单独监控。Agent 出问题时你能快速定位是模型推理错了、工具调用失败了、还是编排逻辑有 bug。我见过太多Agent 不工作了但不知道哪出问题的案例根源就是没分层所有逻辑糊在一起。第三是团队协作。大公司里做 Agent 往往不是一个团队的事模型团队、平台团队、业务团队各管一摊。分层让每个团队有清晰的交付边界模型团队交付模型服务平台团队交付编排和协作能力业务团队只管在应用层搭自己的场景。这种分工在手册的产品矩阵里体现得特别明显。3. 核心层级的细节解析与实操要点3.1 编排层单个 Agent 的大脑怎么搭编排层是大多数人接触 Agent 开发的第一站也是最容易做砸的一层。我见过太多项目编排逻辑写得像一团乱麻加个新工具就要改一堆代码。手册里对编排层的描述虽然简洁但透露出的设计原则很值得琢磨。核心原则是把规划和执行分开。规划阶段Agent 根据用户请求和可用工具列表生成一个任务计划执行阶段按计划逐步调用工具、收集结果。这个分离的好处是规划可以复用、可以缓存、可以人工审核而执行可以并行、可以重试。实操上我建议你这样组织编排层的代码结构一个 Planner 模块负责生成计划一个 Executor 模块负责执行计划一个 Memory 模块负责维护状态三者通过明确定义的数据结构通信。计划本身用一个结构化的对象表示比如包含步骤列表、每步的工具名和参数、步骤之间的依赖关系。这样即使后面要换成多 Agent 协作这套结构也能直接复用。提示规划阶段一定要给模型一个明确的工具清单和每个工具的用途说明否则模型很容易幻觉出不存在的工具或者用错工具。我踩过这个坑后来在 Prompt 里把工具描述写得非常详细错误率立刻降下来了。还有一个细节是状态压缩。长对话场景下上下文会迅速膨胀。我的做法是维护一个工作记忆和一个长期记忆工作记忆只保留最近几轮和当前任务相关的信息长期记忆存到向量库里按需检索。这样既控制了 token 消耗又不会丢失关键信息。3.2 协作层与 Agent2Agent多 Agent 怎么不打架协作层是这份手册里我认为最有价值的部分因为它对应的正是当前企业落地最痛的点单个 Agent 能力有限多个 Agent 怎么协同。Agent2Agent 协议的核心思想是给 Agent 之间定义一套标准的通信契约。每个 Agent 对外暴露自己的能力描述能做什么、需要什么输入、产出什么输出其他 Agent 通过这套描述来发现和调用它。这有点像微服务里的服务注册与发现只不过服务换成了 Agent。为什么需要标准协议因为如果没有标准每两个 Agent 之间的通信都要单独写适配代码N 个 Agent 就是 N 平方的复杂度。有了标准协议新增一个 Agent 只需要让它实现协议就能被现有系统发现和调用。实操中协作层要解决三个具体问题。任务分发一个复杂请求进来怎么决定交给哪个 Agent。常见做法是有一个协调者 Agent负责拆解和分发它自己不干活只做调度。上下文传递Agent 之间传递的不只是任务描述还有必要的上下文但上下文不能无限传要有选择地传。结果汇总多个 Agent 的产出怎么合并成一个最终答案这往往需要一个汇总者角色。注意多 Agent 系统最容易出的问题是循环调用和责任不清。A 把任务给 BB 觉得该 C 做C 又推回给 A死循环。解决办法是给每个任务加一个明确的归属标记和超时机制超过一定轮次还没结果就上报人工。3.3 工具与数据层权限和记忆是两大命门工具与数据层看起来最接地气但恰恰是最容易埋雷的地方。我把它拆成工具和数据两块来说。工具这块核心是权限最小化。Agent 能调用的每个工具都要明确它需要什么权限并且只授予必要的权限。比如一个只读查询工具就绝不给它写权限。企业场景下工具调用还要走审计每次调用谁、调了什么、返回了什么都要留痕。这不是为了合规好看而是出问题时能快速定位。数据这块核心是记忆的分层。短期记忆放上下文里长期记忆放向量库或知识图谱里。检索的时候要注意不是所有历史信息都值得检索要有相关性过滤。我常用的做法是给每条记忆打上时间戳和重要性标签检索时综合考虑相关性和时效性。这里有个实操技巧工具描述要写得像给新员工的说明书。模型判断用哪个工具全靠你给的描述。描述里要写清楚这个工具干什么、什么时候用、输入输出格式是什么、有什么限制。我见过有人把工具描述写成一句话结果模型频繁用错改成详细描述后准确率大幅提升。3.4 模型层与基础设施层选型不是越贵越好模型层和基础设施层是地基虽然不直接面向用户但决定了整个系统的上限和成本。模型选型上我的经验是分级使用。规划、推理这类需要强能力的任务用大模型格式转换、简单分类这类任务用小模型甚至专用模型。手册里虽然没有明说成本数字但企业级场景下模型调用成本是绕不开的分级使用能省下相当可观的费用。基础设施层企业通常用云服务。选型时除了价格要重点看三件事网络延迟模型和工具在同一区域能省不少时间、权限体系能不能和公司现有的账号体系打通、可观测性有没有现成的监控和日志工具。这三件事在 demo 阶段感觉不到一上生产就全是问题。4. 产品矩阵与实操落地路径4.1 从 Vertex AI 到 no-code产品矩阵怎么对应六层Google 的 Agent 产品矩阵不是零散的一堆工具而是和六层架构一一对应的。理解这个对应关系你就能明白每个产品该在什么时候用。Vertex AI 对应的是模型层和基础设施层提供模型托管、训练、部署的能力。Agent Builder 对应编排层提供可视化的 Agent 编排能力。Agent2Agent 协议对应协作层定义 Agent 之间的通信标准。各种连接器和数据服务对应工具与数据层。而 no-code 平台对应应用层让不懂代码的业务人员也能搭 Agent。这个矩阵的设计逻辑是让不同角色用不同的入口。算法工程师用 Vertex AI 调模型平台工程师用 Agent Builder 搭编排业务人员用 no-code 搭场景。各司其职互不干扰。4.2 no-code 搭建 Agent 的真实体验与边界no-code 是这份手册里最吸引眼球的部分也是热词里反复出现的。我实际用过几个 no-code Agent 平台说说真实感受。no-code 的优势很明确上手快、迭代快、业务人员能自己改。一个简单的客服问答 Agent用 no-code 平台可能半小时就能搭出来换成写代码至少要一天。对于需求变化快的业务场景这个速度优势非常关键。但 no-code 有明确的边界。复杂逻辑、精细的性能优化、特殊的工具集成这些 no-code 做不了或者做得很别扭。我的建议是用 no-code 做原型和简单场景一旦场景变复杂就迁移到代码方案。不要指望 no-code 能解决所有问题也不要因为 no-code 好用就放弃代码能力。提示选 no-code 平台时重点看它能不能导出成代码或者 API。有些平台搭出来的东西只能在平台内跑一旦要集成到现有系统就抓瞎。能导出的平台迁移成本低很多。4.3 一套可复现的企业级 Agent 落地步骤把前面的内容串起来我给一套我自己验证过的落地步骤你可以直接参考。第一步明确场景和边界。先想清楚这个 Agent 要解决什么问题、服务谁、不做什么。边界不清是 Agent 项目失败的头号原因。第二步选模型和基础设施。根据任务复杂度选模型根据公司现状选基础设施。这一步不要过度设计先用最简单的方案跑起来。第三步定义工具和数据。列出 Agent 需要调用的工具写好每个工具的描述明确权限。数据方面确定哪些信息放上下文、哪些放向量库。第四步搭编排逻辑。先用代码或 no-code 搭一个单 Agent 版本跑通基本流程。这一步的目标是能用不是好用。第五步引入协作。当单 Agent 搞不定时拆成多个 Agent用 Agent2Agent 协议连接。这一步要谨慎多 Agent 不是越多越好。第六步加监控和审计。上线前一定要有日志、监控、审计。Agent 的行为不像传统程序那么确定没有可观测性就是盲人摸象。第七步迭代优化。收集真实使用数据持续优化 Prompt、工具描述、编排逻辑。Agent 系统是养出来的不是一次搭好的。5. 常见问题与排查技巧实录5.1 Agent 不调用工具或调错工具怎么办这是最高频的问题。排查思路按顺序来先看工具描述是否清晰再看模型是否理解任务最后看编排逻辑是否有 bug。工具描述问题占大多数。描述要包含工具用途、适用场景、输入参数格式、输出格式、限制条件。我习惯给每个工具写一段什么时候用我的说明效果很好。如果描述没问题那就是模型能力问题。换更强的模型或者在 Prompt 里加几个用哪个工具的示例few-shot通常能解决。5.2 多 Agent 协作时上下文丢失怎么破上下文丢失的根源是传递时做了过度压缩。我的做法是分层传递任务描述必传关键上下文必传历史对话按相关性选择性传。同时给每个 Agent 一个回查能力需要时能主动去查完整上下文。还有一个技巧是给上下文加摘要。长上下文先摘要再传既省 token 又保留关键信息。摘要由模型生成但要有校验机制防止摘要丢关键信息。5.3 成本失控的排查与优化成本失控通常有三个原因模型用太大、上下文太长、调用次数太多。优化顺序先看能不能换小模型再看能不能压缩上下文最后看能不能减少调用次数。我做过一次优化把简单任务从大模型换成小模型成本直接降了七成效果几乎没差别。5.4 常见问题速查表问题现象可能原因排查方向解决建议Agent 不调用工具工具描述不清检查工具描述完整性补充用途、参数、示例调错工具模型理解偏差检查 Prompt 和示例加 few-shot 示例上下文丢失传递时过度压缩检查传递逻辑分层传递加回查成本过高模型过大或上下文过长分析调用日志分级用模型、压缩上下文多 Agent 死循环责任不清检查任务归属加归属标记和超时响应慢串行调用过多分析调用链能并行的并行5.5 几个我踩过的坑第一个坑是过早引入多 Agent。一开始就搞一堆 Agent 协作结果调试成本极高。后来改成先做单 Agent确实需要了再拆效率高很多。第二个坑是忽视工具权限。早期没做权限控制Agent 能调用所有工具后来发现有个工具能改数据库吓出一身冷汗。权限最小化必须从第一天就做。第三个坑是没有可观测性。Agent 出问题时只能靠猜后来加了详细日志和监控排查效率提升十倍不止。6. 我对这套架构的几点个人体会通读手册加上自己动手实践之后我最深的体会是企业级 Agent 的难点从来不在模型而在工程。模型能力每年都在涨但权限、状态、协作、可观测性这些工程问题不会因为模型变强就自动消失。六层架构的价值是给这些工程问题划出了清晰的解决边界。你不需要一次把六层都做完美但要知道每一层该解决什么问题遇到问题时知道去哪一层找答案。Agent2Agent 协议我觉得是未来一两年最值得关注的方向。单 Agent 的能力天花板已经比较清楚了多 Agent 协作才是打开企业场景的钥匙。而协作的前提是标准协议谁先把协议做扎实谁就能在生态里占住位置。no-code 我会继续用但只用在合适的场景。它是降低门槛的工具不是替代工程能力的魔法。真正复杂的企业场景代码能力还是绕不开的。最后分享一个小技巧搭 Agent 时先把它当成一个新员工来设计。新员工需要什么——清晰的任务说明、明确的权限、能查资料、能问同事、有反馈机制。把这些想清楚Agent 的架构自然就清晰了。这个类比帮我解决过很多设计上的纠结希望对你也有用。
