Skip to content

托管智能体

Supported in ADKPython v2.4.0Preview

托管智能体让你可以在 ADK 流程中使用 Google 提供的第一方开箱即用智能体，这些智能体由 Managed Agents API 支持。托管智能体可通过 Gemini API 和 Agent Platform 获取。ManagedAgent 类会连接到一个在专用的服务器端执行环境中运行的托管智能体（例如 Antigravity 智能体），因此你无需管理沙箱或编写客户端函数声明即可获得强大的内置能力。

ManagedAgent 实现了与其他 ADK 智能体相同的 BaseAgent 契约，因此你可以单独使用它，也可以直接将其放入 ADK 流程中。当你希望拥有一个由服务器托管的、具有专用内置工具的健壮智能体，而不是自己构建和运营该环境时，它是一个很好的选择。

什么是托管智能体？

托管智能体是一种智能体，其推理、工具和执行环境由 Google 通过 Managed Agents API 托管和运营，而非由你自己的 ADK 进程运行。ManagedAgent 不会发出标准的 generate_content 调用，而是在服务器端创建交互，并将结果流式传输回你的 ADK 流程。托管智能体提供了多项内置优势：

  • 第一方开箱即用智能体： 通过引用 agent_id 即可连接到现成的智能体（例如 Antigravity 智能体）。
  • 内置的服务器端执行： 网页搜索和代码执行等能力在服务器上的托管沙箱中运行，无需配置或保护本地沙箱。
  • 无需客户端函数声明： 服务器端工具在托管智能体上配置，因此你无需在本地声明或执行它们。

何时使用托管智能体与自行构建

托管智能体和 ADK 智能体解决的是不同的问题。在两者之间选择，主要是开箱即用的能力与细粒度控制之间的权衡。

  • 托管智能体提供开箱即用的强大智能体，但灵活性有限。工具集是预定义的且在服务器端运行，智能体仅在托管环境中运行，不支持客户端或 MCP 工具。
  • ADK 智能体（例如 LlmAgent）让你可以对模型、指令、工具（包括自定义函数工具和 MCP 工具）以及执行位置进行细粒度控制。

前提条件

ManagedAgent 支持两种后端。请完成你计划使用的后端的前提条件：获取凭据和 agent_id。

Gemini API 后端

  • 认证： 获取 Gemini API 密钥并将其设置为 GEMINI_API_KEY 环境变量。
  • 智能体 ID： 你需要一个 agent_id 来连接。你可以：
    • 按照 Gemini API Agents 文档 创建一个新的智能体。
    • 使用开箱即用的智能体 ID，例如下面示例中使用的 antigravity-preview-05-2026。

Agent Platform 后端

  • 认证： Agent Platform 需要 Google Cloud 凭据。请按照 Agent Platform 设置说明 认证你的本地环境（例如使用 gcloud auth application-default login）。
  • 位置： Managed Agents API 仅从 global 位置提供服务。ManagedAgent 在 Agent Platform 后端上强制连接到 global。
  • 智能体 ID： 与 Gemini API 一样，你需要一个 agent_id。使用创建和管理智能体指南创建一个，或使用你的项目可用的开箱即用智能体 ID。

快速开始

以下示例创建了两个托管智能体：一个使用网页搜索回答问题，另一个通过在服务器端运行代码来解决计算问题。两者都在托管环境中运行其工具（environment={'type': 'remote'}）。

import os
from google.adk.agents import ManagedAgent
from google.adk.tools import google_search
from google.genai import types

# 确保你已设置 MANAGED_AGENT_ID 和正确的环境配置
_AGENT_ID = os.environ.get('MANAGED_AGENT_ID', 'antigravity-preview-05-2026')

managed_search_agent = ManagedAgent(
    name='managed_search_agent',
    description='Answers questions that need fresh, grounded information from the web.',
    agent_id=_AGENT_ID,
    environment={'type': 'remote'},
    tools=[google_search],
)

# 使用原始 types.Tool 的托管代码执行智能体
managed_code_execution_agent = ManagedAgent(
    name='managed_code_execution_agent',
    description='Solves computational questions by running code server-side.',
    agent_id=_AGENT_ID,
    environment={'type': 'remote'},
    tools=[types.Tool(code_execution=types.ToolCodeExecution())],
)

工作原理

当你调用 ManagedAgent 时，ADK 会通过 Interactions API 将你的请求发送到托管智能体，并将部分和最终结果实时流式传输回你的 ADK 流程。推理、工具和执行都在 Google 的托管环境中运行，而非在你的 ADK 进程中。

ManagedAgent 如何映射到 Managed Agents API

ADK ManagedAgent 不会创建或注册新的托管智能体资源。它连接到后端上已存在的智能体（由 agent_id 指定的智能体），并将其配置（如 tools 和 environment）作为运行时的按交互覆盖应用。用 Managed Agents API 的术语来说，ADK 完全在数据平面（Interactions API）上工作，不触及控制平面（Agents API，用于创建和管理智能体资源）。有关这两个平面的区别，请参阅 Managed Agents API 系统架构。

本地会话与远程状态

ManagedAgent 几乎不在本地保留状态。ADK 会话仅在其发出的事件上持久化两个值：previous_interaction_id 和沙箱 environment_id。在每个新回合中，智能体通过扫描之前的会话事件来恢复这两个值，然后重用它们以继续对话及其沙箱。

其他所有内容都保存在服务器端。Managed Agents API 拥有沙箱环境和完整的交互历史记录，该远程交互（而非本地会话）才是继续对话的真实来源。响应文本同时出现在本地 ADK 事件和远程交互历史中，但 ADK 仅存储恢复和重用远程状态所需的 ID；它永远不会重新发送之前的回合。

限制

  • 位置固定（仅限 Agent Platform）： 对于 Agent Platform 后端，Managed Agents API 目前仅从 global 位置提供服务。区域性端点会引发错误。
  • 仅限服务器端工具： 不支持客户端执行的工具（Python 函数、可调用对象）和 MCP 工具，会引发 NotImplementedError。
  • 仅限流式传输： 智能体使用流式交互（stream=True）。后台轮询执行和严格非流式连接尚未完全支持。
  • 后端差异： Gemini API 和 Agent Platform 后端目前表现出略有不同的行为模式。请针对你计划使用的具体后端进行测试。

后续步骤