ContextQMD
Back to Adk Python

ManagedAgent

docs/guides/agents/managed_agent/index.md

2.6.09.6 KB
Original Source

ManagedAgent

Introduction

ManagedAgent allows you to leverage managed agents backed by the Managed Agents API (interactions.create) via either the Gemini Enterprise Agents Platform (GEAP, formerly Vertex) or the Gemini API from within your ADK flows. It is particularly useful when you want to utilize Google's powerful first-party, out-of-the-box agents (like the Antigravity agent) that have specialized server-side execution environments built-in without requiring client-side function declarations.

This solves the developer problem of needing a robust, server-hosted environment for agents that require specialized built-in capabilities, rather than managing sandbox environments and Python code execution locally. ManagedAgent can be used as a standalone agent, integrated directly into a workflow, or encapsulated as a tool via AgentTool so that a coordinating LlmAgent can delegate specialized tasks to it.

Prerequisites

The ManagedAgent supports two distinct backends: the Gemini API backend and the Gemini Enterprise Agents Platform (GEAP) backend. Depending on which backend you intend to use, you must satisfy the corresponding prerequisites for authentication and obtaining an Agent ID.

Option 1: Gemini API Backend

  • Authentication: You must obtain a Gemini API key. Set this as the GEMINI_API_KEY environment variable.
  • Agent ID: You need an agent_id to connect to. You can either:
    • Create a new agent by following the Gemini API Agents documentation.
    • Use an out-of-the-box agent ID, such as antigravity-preview-05-2026, which is commonly used in our examples.

Option 2: Gemini Enterprise Agents Platform (GEAP) Backend

  • Authentication: GEAP (formerly Vertex) requires Google Cloud credentials. Follow the GEAP setup instructions to authenticate your local environment (e.g., using gcloud auth application-default login).
  • Agent ID: Similar to the Gemini API, you need an agent_id. You can either:

Get started

Here is a minimal implementation of ManagedAgent demonstrating its use.

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

# Ensure you have the MANAGED_AGENT_ID and the proper environment config
_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],
)

# A managed code execution agent using raw 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())],
)

To see an orchestrator pattern using this code, you could wrap them using AgentTool:

python
from google.adk.agents import LlmAgent
from google.adk.tools.agent_tool import AgentTool

# The local coordinator delegates tasks to the server-backed agents
root_agent = LlmAgent(
    name='managed_tool_coordinator',
    description='Calls managed specialists as tools and composes the answer.',
    tools=[
        AgentTool(agent=managed_search_agent),
        AgentTool(agent=managed_code_execution_agent),
    ],
)

Create and use a custom managed agent

ManagedAgent connects to an existing managed agent by agent_id. You can shape that agent's behavior inline, with no resource creation: set instruction for a persona and pass server-side tools such as google_search (see Get started).

Create a custom managed-agent resource when you instead want a persistent, named agent whose persona and server-side tools are baked into the resource and reusable by id across apps and sessions. Create it through the control plane, then point ManagedAgent at its id. The genai client ManagedAgent already holds (managed_search_agent.api_client) exposes both planes: interactions (data plane) and agents.create / agents.delete (control plane), so you can create with the same client:

python
created = managed_search_agent.api_client.agents.create(
    id='adk-custom-search-agent',
    base_agent='antigravity-preview-05-2026',
    system_instruction='You are a concise research assistant. ...',
    tools=[{'type': 'google_search'}],
)
# created.id is the agent id ManagedAgent(agent_id=...) connects to.

Creating a custom agent requires the GEAP/Vertex backend (global location); its system_instruction and tools are fixed at create time, and creation is asynchronous (the agent takes a short while to become ready). See the custom_agent sample for a runnable example with --create / --delete flags.

How it works

The ManagedAgent implements the BaseAgent contract but bypasses standard generate_content calls, instead sending interactions via _create_interactions with background=True. It natively streams partial events and terminal events in real-time back to the ADK Runner or parent flow.

When using the GEAP backend, it enforces a connection to the global location since the Managed Agents API is solely available globally. Because it runs remotely, tools are translated into standard ToolParam formats for interactions; any raw google.genai.types.Tool configs are passed through to the backend, enabling server-side code execution or remote google search seamlessly.

State: local session vs. remote

ManagedAgent keeps almost no state locally. The ADK session only persists two values on the events it emits: the previous_interaction_id and the sandbox environment_id. On each new turn the agent recovers both by scanning prior session events, then reuses them so the conversation and its sandbox continue.

Everything else lives server-side. The Managed Agents API owns the sandbox environment and the full interaction history, and that remote interaction — not the local session — is the source of truth for continuing a conversation. Response text appears in both places (the local ADK events and the remote interaction history), but ADK stores only the ids it needs to recover and reuse the remote state; it never re-sends prior turns.

System instruction

Set instruction on ManagedAgent to send a system instruction to the Managed Agents API, mirroring LlmAgent.instruction. It accepts a plain string — which may embed {state_var} / {artifact.name} / {var?} placeholders resolved from session state and artifacts at request time — or an InstructionProvider callable that is invoked with a ReadonlyContext and bypasses placeholder injection. The resolved instruction is forwarded as the interaction's system_instruction on every turn, including chained turns; an empty instruction (the default) sends none.

python
from google.adk.agents import ManagedAgent

root_agent = ManagedAgent(
    name='managed_persona_agent',
    agent_id='antigravity-preview-05-2026',
    environment={'type': 'remote'},
    instruction='You are a terse assistant. Answer in a single sentence.',
)

Advanced applications

Tool encapsulation for orchestration

  • Problem solved: Sometimes a single LLM request needs to compose results from multiple independent, robust specialists without losing control of the execution turn.
  • Implementation: Encapsulate each ManagedAgent instance within its own separate AgentTool and provide them as a list of tools to an LlmAgent coordinator. The coordinator will invoke the managed agents (which run their sandboxed logic server-side), collect the results, and then compose the final synthesized response natively.

Limitations

  • Location pinned (GEAP only): For the GEAP backend, the Managed Agents API is currently only served from the global location. Enterprise clients using regional endpoints will raise an error.
  • Server-side tools only: Client-executed tools (Python functions, callables) and MCP tools are not supported. Providing these will raise a NotImplementedError.
  • Streaming only: The agent only supports streaming interactions. Background-polling execution or strictly non-streaming connections are not yet fully supported (it natively uses stream=True and yields events).