Skip to content

Commit 508e742

Browse files
haranrkkoverholt
haranrk
and
koverholt
authored
docs(agents): add Managed Agents page (Managed Agents API x ADK) (#1949)
* docs(agents): scaffold managed agents page and nav entry * docs(agents): add managed agents get-started and decision guidance * docs(agents): complete managed agents page (how it works, limitations, resources) * docs(agents): simplify managed agents "how it works" and refine copy Replace the internals-heavy "How it works" paragraph with a high-level description that links to the Interactions API, drop the scenario table in favor of the two-bullet comparison, add a note on how ManagedAgent maps to the Managed Agents API (data plane vs. control plane), and remove em-dashes throughout. * docs(agents): point Interactions API link to the Gemini API overview * Clean up managed agents page naming, structure, bullets, and links, and add it to the agents overview --------- Co-authored-by: Kristopher Overholt <koverholt@google.com>
1 parent 944dd43 commit 508e742

3 files changed

Lines changed: 180 additions & 0 deletions

File tree

‎docs/agents/index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,9 @@ dive deeper into how they work and how to use them effectively:
9797
* [**Simple agents:**](/agents/llm-agents/) Explore how to configure agents
9898
powered by AI models, including setting instructions, providing tools, and
9999
enabling advanced features like planning and code execution.
100+
* [**Managed agents:**](/agents/managed-agents/) Use Google's first-party,
101+
out-of-the-box agents (backed by the Managed Agents API) directly in your ADK
102+
flows, with built-in server-side tools like web search and code execution.
100103
* [**Graph workflows:**](/graphs/) Discover how evolve your agents from
101104
plain language instructions to composable, reliable execution paths that
102105
combine AI reasoning with deterministic code logic.

‎docs/agents/managed-agents.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# Managed agents
2+
3+
<div class="language-support-tag">
4+
<span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v2.4.0</span><span class="lst-preview">Preview</span>
5+
</div>
6+
7+
Managed agents let you use Google's first-party, out-of-the-box agents, backed
8+
by the Managed Agents API, from within your ADK flows. Managed agents are
9+
available through the [Gemini API](https://ai.google.dev/gemini-api/docs/agents)
10+
and [Agent
11+
Platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/managed-agents).
12+
The `ManagedAgent` class connects to a managed agent (such as the Antigravity
13+
agent) that runs in a specialized, server-side execution environment, so you get
14+
powerful built-in capabilities without managing sandboxes or writing client-side
15+
function declarations.
16+
17+
`ManagedAgent` implements the same `BaseAgent` contract as other ADK agents, so
18+
you can use it standalone or drop it directly into an ADK flow. It is a good fit
19+
when you want a robust, server-hosted agent with specialized built-in tools
20+
rather than building and operating that environment yourself.
21+
22+
## What are managed agents?
23+
24+
A *managed agent* is an agent whose reasoning, tools, and execution environment
25+
are hosted and operated by Google through the Managed Agents API, rather than
26+
run by your own ADK process. Instead of issuing standard `generate_content`
27+
calls, `ManagedAgent` creates server-side *interactions* and streams the results
28+
back into your ADK flow. Managed agents provide several built-in advantages:
29+
30+
- **First-party, out-of-the-box agents:** Connect to ready-made agents (for
31+
example, the Antigravity agent) by referencing their `agent_id`.
32+
- **Built-in, server-side execution:** Capabilities such as web search and code
33+
execution run in a managed sandbox on the server, with no local sandbox to
34+
provision or secure.
35+
- **No client-side function declarations:** Server-side tools are configured on
36+
the managed agent, so you don't declare or execute them locally.
37+
38+
## When to use managed agents vs. building your own
39+
40+
Managed agents and ADK agents solve different problems. Choosing between them is
41+
mostly a trade-off between out-of-the-box power and fine-grained control.
42+
43+
- **Managed agents** give you a powerful agent out of the box, but with limited
44+
flexibility. The toolset is predefined and server-side, the agent runs only in
45+
the managed environment, and client-side or MCP tools are not supported.
46+
- **ADK agents** (such as [`LlmAgent`](/agents/llm-agents/)) give you
47+
fine-grained control over the model, instructions, tools (including custom
48+
function tools and MCP tools), and where execution happens.
49+
50+
## Prerequisites
51+
52+
`ManagedAgent` supports two backends. Complete the prerequisites for the backend
53+
you plan to use: obtain credentials and an `agent_id`.
54+
55+
### Gemini API backend
56+
57+
- **Authentication:** Obtain a Gemini API key and set it as the `GEMINI_API_KEY`
58+
environment variable.
59+
- **Agent ID:** You need an `agent_id` to connect to. You can either:
60+
- Create a new agent by following the [Gemini API Agents
61+
documentation](https://ai.google.dev/gemini-api/docs/agents).
62+
- Use an out-of-the-box agent ID, such as `antigravity-preview-05-2026`,
63+
which is used in the examples below.
64+
65+
### Agent Platform backend
66+
67+
- **Authentication:** Agent Platform requires Google Cloud credentials. Follow
68+
the [Agent Platform setup
69+
instructions](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/managed-agents/create-manage#before-you-begin)
70+
to authenticate your local environment (for example, with `gcloud auth
71+
application-default login`).
72+
- **Location:** The Managed Agents API is served only from the `global`
73+
location. `ManagedAgent` enforces a connection to `global` on the Agent
74+
Platform backend.
75+
- **Agent ID:** As with the Gemini API, you need an `agent_id`. Create one via
76+
the [Agent Platform Managed Agents
77+
guide](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/managed-agents),
78+
or use an out-of-the-box agent ID available to your project.
79+
80+
## Get started
81+
82+
The following example creates two managed agents: one that answers questions
83+
using web search, and one that solves computational questions by running code
84+
server-side. Both run their tools in the managed environment
85+
(`environment={'type': 'remote'}`).
86+
87+
=== "Python"
88+
89+
```python
90+
import os
91+
from google.adk.agents import ManagedAgent
92+
from google.adk.tools import google_search
93+
from google.genai import types
94+
95+
# Ensure you have the MANAGED_AGENT_ID and the proper environment config
96+
_AGENT_ID = os.environ.get('MANAGED_AGENT_ID', 'antigravity-preview-05-2026')
97+
98+
managed_search_agent = ManagedAgent(
99+
name='managed_search_agent',
100+
description='Answers questions that need fresh, grounded information from the web.',
101+
agent_id=_AGENT_ID,
102+
environment={'type': 'remote'},
103+
tools=[google_search],
104+
)
105+
106+
# A managed code execution agent using raw types.Tool
107+
managed_code_execution_agent = ManagedAgent(
108+
name='managed_code_execution_agent',
109+
description='Solves computational questions by running code server-side.',
110+
agent_id=_AGENT_ID,
111+
environment={'type': 'remote'},
112+
tools=[types.Tool(code_execution=types.ToolCodeExecution())],
113+
)
114+
```
115+
116+
## How it works
117+
118+
When you invoke a `ManagedAgent`, ADK sends your request to the managed agent
119+
via the [Interactions
120+
API](https://ai.google.dev/gemini-api/docs/interactions-overview) and streams
121+
the results, both partial and final, back into your ADK flow in real time. The
122+
reasoning, tools, and execution all run in Google's managed environment rather
123+
than in your ADK process.
124+
125+
!!! note "How `ManagedAgent` maps to the Managed Agents API"
126+
127+
An ADK `ManagedAgent` does not create or register a new managed agent
128+
resource. It connects to an agent that already exists on the backend (the
129+
one named by `agent_id`) and applies its configuration (such as `tools` and
130+
`environment`) as per-interaction overrides at runtime. In Managed Agents
131+
API terms, ADK works entirely on the *data plane* (the Interactions API) and
132+
leaves the *control plane* (the Agents API, which creates and manages agent
133+
resources) untouched. For how these two planes differ, see the [Managed
134+
Agents API system
135+
architecture](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/managed-agents).
136+
137+
### Local session vs. remote state
138+
139+
`ManagedAgent` keeps almost no state locally. The ADK session persists only two
140+
values on the events it emits: the `previous_interaction_id` and the sandbox
141+
`environment_id`. On each new turn the agent recovers both by scanning prior
142+
session events, then reuses them so the conversation and its sandbox continue.
143+
144+
Everything else lives server-side. The Managed Agents API owns the sandbox
145+
environment and the full interaction history, and that remote interaction, not
146+
the local session, is the source of truth for continuing a conversation.
147+
Response text appears in both the local ADK events and the remote interaction
148+
history, but ADK stores only the IDs it needs to recover and reuse the remote
149+
state; it never re-sends prior turns.
150+
151+
## Limitations
152+
153+
- **Location pinned (Agent Platform only):** For the Agent Platform backend, the
154+
Managed Agents API is currently served only from the `global` location.
155+
Regional endpoints raise an error.
156+
- **Server-side tools only:** Client-executed tools (Python functions,
157+
callables) and MCP tools are not supported and raise a `NotImplementedError`.
158+
- **Streaming only:** The agent uses streaming interactions (`stream=True`).
159+
Background-polling execution and strictly non-streaming connections are not
160+
yet fully supported.
161+
- **Backend differences:** The Gemini API and Agent Platform backends currently
162+
exhibit slightly different behavioral patterns. Test against the specific
163+
backend you intend to use.
164+
165+
## Next steps
166+
167+
- **Samples:** [Managed Agent
168+
Basic](https://github.com/google/adk-python/tree/main/contributing/samples/managed_agent/basic)
169+
and [Managed Agent Code
170+
Execution](https://github.com/google/adk-python/tree/main/contributing/samples/managed_agent/code_execution).
171+
- **Backend documentation:** [Gemini API
172+
Agents](https://ai.google.dev/gemini-api/docs/agents) and [Agent Platform
173+
Managed
174+
Agents](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/managed-agents).
175+
- **Related ADK topics:** [Models for agents](/agents/models/), [Multi-agent
176+
workflows](/workflows/), and [Custom tools](/tools-custom/).

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -289,6 +289,7 @@ nav:
289289
- Agents:
290290
- agents/index.md
291291
- Simple agents: agents/llm-agents.md
292+
- Managed agents: agents/managed-agents.md
292293
- Graph Workflows:
293294
- graphs/index.md
294295
- Graph routes: graphs/routes.md

0 commit comments

Comments
 (0)