使用 ADK 实现多代理模式的开发者指南

首页 » Python » 使用 ADK 实现多代理模式的开发者指南

智能体应用程序正在迅速超越经典的“单一大型提示”模式，开发人员需要一个坚实的思维模型来构建多个智能体，而不会陷入混乱。 Google 的代理开发工具包 (ADK) 正是为此而设计的：它允许您构建可靠的多代理系统，连接工具和内存，并将所有内容部署在 Google Cloud 上，从而实现生产级的可观测性、安全性和成本控制。

本指南将带您了解 ADK 支持的主要多代理模式——从简单的父/子层次结构到顺序、循环和并行工作流代理——并展示它们如何融入 Google Cloud 上更广泛的参考架构。 我们还将介绍共享会话状态、委托机制、常见的多代理蓝图，以及在真实环境中部署、保护和运行这些系统的实际方面。

为什么 ADK 中需要多智能体系统？

当一个应用程序由单个、单一的代理提示驱动时，很快就会变得难以进行推理、测试和改进。 庞大的提示信息很脆弱，难以调试，而且随着需求的增长，维护起来也很麻烦。ADK 鼓励你构建一个 多智能体系统（MAS） 每个代理人都有明确的职责，并且协调工作是明确的。

将应用程序构建为多个协作代理，可以实现模块化、专业化和可重用性。 您可以拥有研究代理、评论家、文件写入者、路由器、数据访问代理，并在项目或工作流程中重复使用它们，而不是将相同的逻辑重新嵌入到一个巨型提示符中。

ADK 为您提供实现此目标的具体构建模块：以 LLM 为中心的代理、工作流代理（顺序、并行、循环）和封装非 LLM 逻辑的自定义代理。 它们都继承自一个共同点 BaseAgent因此，它们可以接入同一个编排模型、日志记录、状态处理和工具系统。

随着系统的发展，这种组合模型比临时编排代码或围绕单个模型的深度嵌套函数调用链具有更好的可扩展性。 您可以将认知负荷控制在可控范围内：每个代理都有明确的任务，并且与其他代理有明确的交互界面。

用于组合代理的 ADK 原语

ADK 提供了一小群基本元素，您可以将它们组合起来，表达出非常丰富的多智能体架构。 理解这些核心概念，就能更容易地对更高层次的模式进行推理。

第一个基本要素是智能体层级结构：每个智能体都可以声明一个列表 sub_agents形成一棵树，只有一个 root_agent 在顶部。 当你把孩子送入 sub_agentsADK 会自动连接它们的 parent_agent 引用并强制规定给定实例只有一个父实例（否则为空） ValueError （被提起）。

这种层级结构不仅仅是装饰：它定义了哪些代理可以委托给哪些代理，并且是工作流代理和 LLM 驱动的转移所使用的范围。 从任何代理处，你都可以通过以下方式向上移动： agent.parent_agent 或者找到他们的后代 agent.find_agent(name)这对于调试来说非常方便。

除了基本的LLM代理之外，ADK还引入了专用工作流代理—— SequentialAgent, ParallelAgent 与 LoopAgent ——其职责不是“思考”，而是协调下属代理人。 它们都共享相同的接口，但实现了不同的执行策略：按顺序运行、并行扇出或在具有明确终止规则的循环中迭代。

第三个基本要素是通信层，其核心是共享的 Session 以及 state 字典。 会话状态就像一块公共白板：任何代理或工具都可以写入中间结果或标志，而同一调用中的其他代理可以读取它们，通常是通过在其指令中使用键模板来实现的（例如）。 {PLOT_OUTLINE?}).

ADK 中代理如何相互通信

ADK 支持代理之间三种互补的通信模式：共享会话状态、LLM 驱动的传输和显式调用。 AgentTool. 为每次交互选择合适的交互方式，可以使您的系统既富有表现力又可预测。

共享会话状态（session.state是最简单、最普遍的机制。 在单次调用中，所有代理看到的都是相同的 Session 通过对象 InvocationContext工具或回调可以做到这一点 context.state = value，后续的代理可以通过以下方式检索它： context.state.get("data_key")对于LLM代理，设置 output_key 自动将他们的最终答案保存到该密钥下。

LLM 驱动的委托，有时被称为“代理转移”，允许 LLM 根据指令和代理描述决定何时将任务移交给另一个代理。 在内部，该模型会发出一个特殊的函数调用，例如 transfer_to_agent(agent_name="screenwriter")ADK的 AutoFlow 拦截此调用，并将执行重新路由到允许范围内的选定代理（根据配置，可以是父代理、子代理、兄弟代理）。

显式调用 AgentTool 为您提供了一种更可控、更像函数的方式，可以从一个代理调用另一个代理。 你将目标代理实例包装在 AgentTool将其添加到呼叫者的 tools 列表中，LLM 可以像选择其他任何功能一样选择该工具。调用时， AgentTool.run_async 执行子代理，将状态和工件合并回去，并将子代理的响应作为工具结果返回。

这三个通道满足了大多数多代理需求：通过状态进行异步数据传递，通过传输进行灵活路由，以及通过工具进行紧密同步调用。 在更复杂的设计中，你通常会将它们混合在一个树中：一个路由器，用于将请求转发给子节点；一个专家，用于使用状态进行通信；以及一两个代理，可用作临时委托的工具。

构建模块：LLM 代理、工作流代理和自定义代理

ADK 中的大多数 MAS 拓扑结构都是三种代理类型的组合：基于 LLM 的代理、工作流代理和自定义代理。 每个类别都解决了编排问题的不同方面。

LLM代理将大型语言模型和可选工具、回调函数和输出路由封装在一起。 BaseAgent. 把它们想象成你的“思考”组件：它们解释用户输入，调用工具，更新状态，然后回答用户或将问题转交给另一个代理。

工作流代理扮演管理者的角色，而不是工作者的角色：它们不会自行推理，但它们控制子代理执行的顺序、并行性和重复性。 SequentialAgent 它的孩子一个接一个地出生，共享着同样的资源。 InvocationContext, ParallelAgent 它分布在多个共享状态但具有不同历史分支的分支上，并且 LoopAgent 重复执行序列，直到满足停止条件为止。

海关人员延伸 BaseAgent 当内置的编排策略不足以满足需求时，可以使用任意非 LLM 逻辑。 例如，您可以实现一个自定义调度程序，根据指标有条件地执行代理，或者集成一个业务规则引擎，根据监管约束确定要运行哪个子流程。

这种通用编排原语和可插拔逻辑的结合，使得 ADK 不仅适用于演示，也适用于严肃的企业工作负载。 您可以先使用标准工作流代理，只有当需求变得特殊时，才需要使用其他代理。 CustomAgent.

会话状态和内存模式

ADK 中的会话状态既支持短期对话记忆，也支持代理之间的结构化数据传递。 每次对话都会用到 Session 保存消息历史记录且可变的对象 state 该调用中所有代理均可访问该字典。

写入状态通常是在工具或回调函数内部完成的，使用…… ToolContext or CallbackContext 目的。 例如，像这样的工具 save_attractions_to_state(tool_context, attractions: List) 可以将新的景点与已存储的景点合并。 state向代理返回简单的状态消息，同时 ADK 将状态增量持久化到会话中。

通过嵌入在说明中的关键模板，使从状态中读取数据变得符合人体工程学。 当一条指令包含 {my_key?}ADK 将注入 state 如果存在，问号表示它是可选的，这样即使缺少密钥，代理也不会出错。这在“研究→撰写→审阅”之类的工作流程中至关重要，因为每个步骤都会读取前一步保存的内容。

对于跨回合的对话记忆，关键在于重复使用相同的信息。 Session 对于后续用户消息，将不再每次都创建新消息。 通过共享会话，智能体可以看到之前的回合，并能处理后续问题、纠正错误以及进行多步骤规划。如果您不小心为每个回合都创建了一个全新的会话，智能体的行为就像失忆了一样：它无法将后续问题与之前的上下文关联起来。

状态在工作流代理中也扮演着重要角色，例如 LoopAgent它们依赖于计数器、反馈列表或标志等持久键来决定是否需要更多迭代。 评论员可能会在评论中添加评论。 CRITICAL_FEEDBACK 在每次迭代中，规划者或改进者都会读取该关键信息，以便在下一次迭代中改进计划。

SequentialAgent：明确地呈现线性工作流

SequentialAgent 当您有一系列必须按固定顺序执行的步骤时，这是您的首选模式。 把流程想象成“分析需求→研究→起草→保存到文件”或者“确定目的地→规划路线→预订运输”。

在 ADK 中， SequentialAgent 包含一个列表 sub_agents 并逐一运行它们，传递相同的 InvocationContext 贯穿整个链条。 由于 Session 与 state 如果共享，您可以让第一个代理将其结果存储在 output_key="destination" 下一位代理人通过以下方式阅读了它 {destination} 说明书中没有任何胶水代码。

一个经典的例子是电影提案生成器：一个接待根代理与用户对话，然后将工作交给…… SequentialAgent 这会先叫一名研究员，然后叫一名编剧，最后叫一名文件撰写员。 用户只能看到最终结果，但 ADK Web 中的事件图揭示了内部树状结构：greeter → film_concept_team → 。

与显式手动编排相比 if/elif 代码块和函数调用， SequentialAgent 保持控制流的声明式特性，并最大限度地减少样板代码。 您只需声明一次序列，并将其视为运行器或 UI 中的单个可调用代理，同时利用会话状态在步骤之间传递数据。

顺序工作流还可以与其他工作流代理很好地结合：您可以将循环或并行扇出嵌入到更长的链中作为其中一个步骤。 这样就构建出了更高级的流程，例如“迭代故事质量，然后进行票房和选角分析，然后撰写综合报告”。

LoopAgent：迭代改进和编写室

LoopAgent 专为需要多次反复加工才能达到质量标准的任务而设计。 与其采用“一次生成，然后听天由命”的单一方法，不如将提案、批评和改进的过程编码起来。

典型的循环配置包括研究员、生成器（例如编剧）和评论家等代理，他们在多轮合作中发挥作用。 在每一次迭代中，研究人员可能会更新背景事实，编剧可能会调整大纲或计划，而评论家则会根据明确的指导方针对其进行评估，以决定是否需要进行更多迭代。

循环在两种情况下停止：达到 max_iterations 或者由子代理发出工作已完成的信号。 ADK 公开了一个类似这样的内置工具。 exit_loop 评论家可以在计划、大纲或设计通过其内部检查清单时发出这样的请求。 LoopAgent 也尊重 escalate=True 标志在 Event 行动，为你提供另一种提前突破的方法。

持久会话状态是关键：代理会读取类似这样的键。 PLOT_OUTLINE, research or CRITICAL_FEEDBACK 并对每次修改进行改进或补充说明。 这种模式有效地模拟了一个“编剧室”，专家们在其中集思广益、提出批评意见并进行润色，直到有人宣布作品完成为止。

通过结合 LoopAgent - SequentialAgent这样，您可以将整个迭代循环作为更大的端到端工作流程中的一个步骤。 例如， writers_room (LoopAgent) 可能会先运行以生成一个大致的流程图，之后…… file_writer 代理保存结果并附加其他报告。

ParallelAgent：扇出并收集以执行独立任务

ParallelAgent 实现经典的“扇出/聚集”模式，用于独立但共享上下文的任务。 与其依次运行 N 个研究步骤，不如一次性运行所有步骤，等待所有步骤完成，然后汇总它们的输出。

在内部， ParallelAgent 赋予每个子代理一个独特的 InvocationContext.branch - 喜欢 ParentBranch.ChildName ——同时仍然共享相同的 session.state. 这意味着他们都可以像这样解读初始上下文 PLOT_OUTLINE但应该将输出写入不同的状态键（例如）。 box_office_report, casting_report）以避免冲突。

一个常见的例子是电影提案的“前期制作团队”：一位经纪人根据类似电影估算票房潜力，另一位经纪人提出选角方案，两者并行进行。 随后 file_writer 然后使用每个子结果的关键模板生成报告，并将其保存到磁盘。

并行工作流显著降低了宽查询和场景中的延迟 实时数据分析如果您需要博物馆推荐、音乐会选择和周末餐厅推荐，同时运行三个专业代理比依次查询它们要快得多。 扇出之后，合成代理从状态中读取所有结果，并为用户生成统一的响应。

并行步骤几乎总是嵌入在……之中 SequentialAgent 首先准备上下文，然后运行 ParallelAgent然后继续进行汇总和报告。 一旦您熟悉了 ADK 的工作流代理，这种模式就很容易识别和重复使用。

使用 ADK 原语的编排模式

一旦你掌握了层次结构、工作流代理和状态，你就可以直接在 ADK 中实现几种经典的多代理模式。 这些模式并非硬编码的基本元素，而是由相同的基本构建模块组合而成。

协调器/调度器模式使用中央 LLM 代理作为用户查询的“路由器”，并由多个专门的子代理提供支持。 协调员读取请求后，要么通过 LLM 驱动的委托将控制权转移给子代理，要么显式地调用专家。 AgentTool美食旅行社、交通运输代理或周末旅游向导都是常见的例子。

顺序流水线模式其实就是一个 SequentialAgent 他们的子女各自执行流程中一个精心设计的步骤。 生成器-评论家流程是一种经典变体：第一个代理编写草稿并将其保存在一个…… output_key第二个代理对其进行分析并保存反馈，然后第三个代理可能会根据该反馈改进结果。

并行扇出/扇出模式表示为 ParallelAgent 嵌套在顺序工作流程中。 并行子程序将结果写入不同的状态键；稍后的合成代理读取这些状态键并给出组合答案。

层级式任务分解自然而然地从父子树中产生。 更高级别的代理会将目标分解为子目标，并通过委托或工具将子目标分配给下级代理，结果会逐级向上反馈。这在研究助理、供应链优化器或财务顾问系统中尤为有用，因为每个子领域都有其专属的代理。

迭代改进 LoopAgent 将生成器-评论家循环形式化为可重用的模式。 该循环多次执行规划器、评论器和改进器代理，使用状态键来持久化最新的计划和相应的反馈，并在达到质量标准或迭代次数上限时停止。

Google Cloud 上多智能体系统的参考架构

除了代理逻辑之外，您仍然需要在某个地方运行您的系统，而 Google Cloud 为生产级多代理部署提供了一个定义完善的参考架构。 从总体上看，该解决方案结合了前端、代理运行时、Vertex AI 模型、安全服务以及可选的工具框架（如 MCP）。

典型的设置是从运行在 Cloud Run 上的前端（通常是聊天界面）开始的。 用户与此用户界面交互，该界面将请求转发给以服务形式提供的协调代理。然后，该协调代理根据用户意图在不同的代理工作流程中进行选择，包括可选的人工干预路径，用户可以在该路径中验证或覆盖代理的决定。

代理本身可以在多种环境中运行：Cloud Run 服务、Google Kubernetes Engine (GKE) 或 Vertex AI Agent Engine。 ADK 涵盖了这些选项，它抽象化了一些运行时细节，使开发人员能够专注于代理逻辑而不是基础架构管道。

所有代理调用都依赖于 Vertex AI 或其他模型运行时进行推理，通常会使用 Model Armor 进行封装，以清理提示和响应。 模型护甲有助于在模型调用之前或之后过滤提示注入尝试、敏感数据泄露或有害内容，从而起到生成组件周围的安全防护作用。

当代理必须以标准化的方式与外部系统（数据库、文件系统或 SaaS API）通信时，MCP（模型上下文协议）工具和服务器就派上了用场。 MCP 定义了代理和工具服务器之间的通用契约，因此代理中的单个 MCP 客户端可以访问由不同团队构建的多个工具，而无需紧密耦合；esto incluye consideraciones sobre 数据存储系统 y cómo exponerlos de forma segura。

代理应用程序的安全性和治理

代理系统引入了超越传统微服务的安全挑战，因为如果不小心，LLM 可能会被诱骗滥用工具或泄露数据。 Google 推荐的方法是将确定性安全控制与 LLM 感知、策略驱动的防御措施相结合；también es clave entender los 极限、危险和风险 de los modelos al diseñar estas defensas。

人工监督仍然至关重要：高影响力流程应包括审批步骤，以便有人可以暂停、审查或否决代理人提出的行动。 这可以建模为一个专门的“人工确认”工具，它将请求呈现给用户界面，并且只有在人类做出响应后才会恢复执行。

代理的访问控制通过 IAM 进行管理：每个代理或服务帐户都应该只有履行其职责所需的最低权限。 如果某个代理被入侵或滥用，其影响范围将受到限制，因为其服务帐户无法访问无关的资源或工具。

策略驱动的工具门控，通过诸如以下组件实现： SecurityPlugin 加上 PolicyEngine允许您在运行某些工具之前要求用户确认。 当策略标记敏感调用时，插件会拦截该调用，发出一个特殊的“请求确认”函数调用，并等待您的应用程序返回结果，从而有效地将人纳入高风险操作的流程中。

标准 Google Cloud 安全功能完善了整个体系：VPC 服务控制可降低数据泄露风险，CMEK 用于客户管理的加密密钥，Cloud Armor 用于 WAF 和 DDoS 防护，IAP 或身份平台用于验证用户身份，以及细粒度的 IAM 用于资源访问。 对于通过 A2A 进行的代理间通信，生产环境中需要或建议使用 TLS 1.2+ 和基于 OAuth 的身份验证。

可靠性、可观测性和成本优化

生产环境中的 MAS 部署必须可靠、可观测且经济高效；ADK 与 Google Cloud 的运维工具集成良好，使这一切成为可能。 您可以对代理、会话和工具进行检测，以便它们的日志和跟踪信息出现在 Cloud Logging 和 Cloud Trace 中。

从可靠性角度来看，设计代理图时应考虑容忍单个组件的故障。 尽可能避免使用单一且不可替代的中央处理器；让独立的代理执行局部任务，这样一条路径的故障就不会导致整个应用程序崩溃；此外，技术员职位 物流配送中的货物平衡 分配货物并减少法洛的蓬托斯。模拟分期失败，以验证压力下的协调行为。

对于模型调用，Vertex AI 支持动态共享配额和预置吞吐量。 共享配额避免了按需付费模式下每个项目严格的限制，而预置吞吐量对于高 QPS、对延迟敏感且不能被限速的工作负载至关重要。监控请求速率和令牌使用情况有助于您决定何时从按需付费切换到预置容量。

成本控制主要取决于智能的模型选择、精心的提示设计以及避免不必要的代币。 尽可能从经济高效的模型入手，保持提示简洁但信息丰富，尽可能明确地要求简短的输出，利用上下文缓存处理重复的大型提示，并在工作负载允许的情况下考虑批量预测。

Cloud Run 资源调优和长期折扣进一步优化了运行时成本。 先使用默认的 CPU/内存配置，观察实际使用情况并进行调整。对于可预测的工作负载，承诺使用量折扣可以显著降低支出。

在可观测性方面，你应该将代理视为监控策略中的一等实体。 记录它们的输入、决策（例如调用哪些工具、委托给哪个代理）和状态变化。使用 Web UI 中的 ADK 事件图调试单个会话，并使用云日志记录和自定义仪表板查看整个集群的趋势。

如果运用得当，这些实践能让你清晰地了解你的多智能体系统：你可以看到哪些代理运行缓慢，哪些工具被过度使用，哪些提示信息过长，以及哪些质量控制循环（例如）存在问题。 LoopAgent 迭代次数超出预期。 这种反馈循环对于随着时间的推移不断优化质量和成本至关重要。

通过将 ADK 的代理原语、工作流模式和状态机制与 Google Cloud 的参考架构、安全堆栈和操作工具相结合，您可以设计出不仅在纸面上很巧妙，而且在生产中可部署、可管理且经济可行的多代理系统。 从简单的父/子代理开始，逐步过渡到顺序、循环和并行编排，您将获得一套工具包，可以将代理理念转化为强大、可维护的应用程序，从而真正创造业务价值。