使用 Google ADK 构建代理

在本指南中，您可以学习如何使用 Google Agent Development Kit (ADK) 构建和运行代理。agent-engine-sdk-adk 包是 ADK 和 MongoDB Atlas 代理引擎之间的适配器。该适配器将 ADK 代理、工作流节点和工具调用转换为平台编排引擎运行和记录的操作。

该适配器具有持久性，因此 ADK 代理以持久性工作流模式运行。Orchestration 引擎（而非 ADK）存储每个会话的省/市/自治区。该平台还存储每次模型调用和工具调用的结果。恢复执行会重播记录的结果，而不是重复执行操作。

Google ADK 考虑因素

当您在 Atlas Agent 引擎上构建 ADK 代理时，请考虑以下关键点：

Google ADK SDK 仅适用于 Python。要使用 Typescript 构建代理，请参阅 Typescript SDK 指南。
您的代理必须在 agent.yaml 文件中将 features.durable_workflow 值设置为 true。如果您省略此字段或将其设置为 false，则第一次调用会失败。要了解有关 agent.yaml 文件中可用字段的更多信息，请参阅 agent.yaml 模式。
agent-engine-sdk-adk 包接受 ADK BaseAgent 或 ADK 2 Workflow 作为代理的根。

先决条件

在开始之前，请确保您具备以下先决条件：

Python 3.11 或更高版本。
uv 包管理器。
已安装并验证 agentengine CLI。要了解如何操作，请参阅创建项目。
Google ADK 2.9.0 或更高版本。要学习如何安装 ADK，请参阅ADK 安装文档。
您的 LLM 提供商的 API 密钥。agentengine create 命令会提示输入密钥，并将其作为 LLM_API_KEY 保存到您的 .env 文件中。

步骤

从 ADK 入门模板创建项目。

使用其中一个 ADK 模板运行 agentengine create 命令：

agentengine create --template hello-world-agent-adk

hello-world-agent-adk 模板创建一个最小化的代理。insurance-agent-adk 模板创建一个保险领域的代理。要学习所有可用模板和 agentengine create 命令选项，请参阅支持的模板。

查看模板代码。

打开项目中的入口点模块。该模板已经注册了一个工具并构建了代理。该模块使用以下 SDK 功能：

@app.tool(): 将函数注册为平台的工具。该装饰器不会自动将工具暴露给您的代理。
@app.entrypoint: 标记返回 ADK 代理的函数。
app.llm(): 封装 ADK BaseLlm 实例，以便平台 Atlas 审核每次模型调用。
app.tools()：返回已应用平台安全包装器的注册工具。

重要

将 app.tools() 函数返回的工具传递给您的代理，而不是传递您使用 @app.tool() 装饰的函数。

在本地运行代理。

在您的代理目录中，运行以下命令以启动本地开发环境：

agentengine dev up

要了解热重载和隔离模式，请参阅在本地运行和测试您的代理。

部署代理。

运行以下命令，一步完成代理的构建和部署：

agentengine deploy --auto

部署的代理还需要您的 LLM API 密钥。要了解如何向部署的代理提供密钥，请参阅预配云密钥。

要了解如何将构建和部署作为单独的步骤进行，请参阅构建代理镜像和部署您的构建。

为工具添加人工查看

要暂停执行直到人工批准工具调用，请将可调用工具函数包装在 ADK FunctionTool 类中，并将 require_confirmation=True 选项传递给构造函数。要暂停执行并收集除批准之外的输入，请使用 ADK LongRunningFunctionTool 类。包装 app.tools() 返回的可调用工具函数，而不是使用 @app.tool() 装饰的原始函数。

以下示例将 app.tools() 返回的每个可调用工具包装在 FunctionTool 类中，以便每个工具调用在运行前都等待人工批准：

import os
from google.adk.agents import LlmAgentfrom google.adk.models.lite_llm import LiteLlmfrom google.adk.tools.function_tool import FunctionTool
@app.entrypointdef build_agent():    return LlmAgent(        name="daily",        instruction="You are a helpful assistant.",        model=app.llm(            LiteLlm(                model="<model-name>",                api_key=os.environ["LLM_API_KEY"],            )        ),        tools=[            FunctionTool(tool, require_confirmation=True)            for tool in app.tools()        ],    )

注意

app.tools() 返回的远程 MCP 工具是 ADK BaseTool 对象，而不是普通的可调用对象，因此您不能使用 FunctionTool 类包装它们。该平台通过 Orchestration 引擎策略和护栏来管理 MCP 工具调用。

响应工具请求

确认回答具有 ADK 对象语法 {confirmed: true|false}。平台将每次暂停记录为 Orchestration 引擎活动，并使用活动 ID 作为中断 ID。

要恢复暂停的执行，请向同一会话上的 invoke 终结点发送请求。在请求中，包含一个 resume_map 对象，该对象将每个待处理暂停的 ID 映射到其回答。您必须在同一个请求中回答所有待处理的暂停。要查找这些 ID，请阅读暂停执行的 suspend_context.interrupts 列表。要了解更多信息，请参阅 Invocation API。

以下示例请求正文回答了两个待处理的暂停。第一个回答批准了一个需要确认的工具调用。第二个回答返回了另一个暂停的工具所请求的输入。

{  "resume_map": {    "<activity-id-1>": { "confirmed": true },    "<activity-id-2>": "us-east-1"  }}

要从 CLI 恢复，请使用 agentengine invoke 命令的 --session 和 --resume 选项。要了解详情，请参阅从 CLI 调用代理。

注意

ADK 代理以持久性工作流模式运行，因此您需要使用 resume_map 请求来恢复它们，而不是使用 Human-in-the-Loop 指南中描述的 decision 请求正文。

支持的代理结构

当您的代理启动时，agent-engine-sdk-adk 包需要完整的 Workflow 和代理结构。平台会根据该结构中的路径记录每个步骤。下表列出了 agent-engine-sdk-adk 包支持的 ADK 功能：

ADK 功能	支持
纯 `BaseAgent` 根	受支持
静态配置的 `Workflow` 节点，包括嵌套的串行和并行图表	受支持
已配置 `sub_agents` 参数，模型通过调用 `transfer_to_agent` 函数选择要运行的子代理	受支持
已配置传输的工作流代理节点	当代理使用以下功能时支持： `mode="chat"`
使用 `AgentTool` 类包装的代理	在执行前被拒绝。请改用已配置的 `sub_agents`。
`NodeTool` 以及在运行时传递给 `run_node()` 的节点	在嵌套代理或节点启动之前被拒绝并报错。

添加其他平台功能

以下平台功能适用于 ADK 代理：

您在 agent.yaml 文件的 mcp 字段中声明的远程 MCP 服务器。平台在启动时发现工具并从 app.tools() 返回它们。要了解更多信息，请参阅使用远程 MCP 服务器。
护栏输出查看。具有 require_review 操作的 llm_output 护栏会暂停模型调用，直到审阅者批准或拒绝输出。通过 resume_map 请求查看输出。

了解详情

后退

构建深度代理