Skip to content

Commit e354840

Browse files
its-amannits-amann
committed
Merge remote-tracking branch 'origin/main' into fix-thought-signature-pruning
2 parents 545f8e2 + ab839d5 commit e354840

2 files changed

Lines changed: 157 additions & 0 deletions

File tree

‎docs/guides/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ This directory contains specific developer guides for the ADK Python implementat
77
### Agents
88
* [LlmAgent Single-Turn Mode](agents/llm_agent/single_turn.md) - Guide on using LlmAgent in single-turn mode.
99
* [LlmAgent Task Mode](agents/llm_agent/task.md) - Guide on using LlmAgent in task mode.
10+
* [ManagedAgent](agents/managed_agent/index.md) - Guide on using ManagedAgent with server-side tools.
1011

1112
### Events
1213
* [Event and NodeInfo](events/event/index.md) - Understanding Event and NodeInfo in workflows.

‎docs/guides/agents/managed_agent/index.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# ManagedAgent
2+
3+
## Introduction
4+
5+
`ManagedAgent` allows you to leverage managed agents backed by the Managed
6+
Agents API (`interactions.create`) via either the
7+
[Gemini Enterprise Agents Platform (GEAP, formerly Vertex)](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/managed-agents)
8+
or the [Gemini API](https://ai.google.dev/gemini-api/docs/agents) from within
9+
your ADK flows. It is particularly useful when you want to utilize Google's
10+
powerful first-party, out-of-the-box agents (like the Antigravity agent) that
11+
have specialized server-side execution environments built-in without requiring
12+
client-side function declarations.
13+
14+
This solves the developer problem of needing a robust, server-hosted environment
15+
for agents that require specialized built-in capabilities, rather than managing
16+
sandbox environments and Python code execution locally. `ManagedAgent` can be
17+
used as a standalone agent, integrated directly into a workflow, or encapsulated
18+
as a tool via `AgentTool` so that a coordinating `LlmAgent` can delegate
19+
specialized tasks to it.
20+
21+
## Prerequisites
22+
23+
The `ManagedAgent` supports two distinct backends: the Gemini API backend and
24+
the Gemini Enterprise Agents Platform (GEAP) backend. Depending on which backend
25+
you intend to use, you must satisfy the corresponding prerequisites for
26+
authentication and obtaining an Agent ID.
27+
28+
### Option 1: Gemini API Backend
29+
30+
* **Authentication**: You must obtain a Gemini API key. Set this as the
31+
`GEMINI_API_KEY` environment variable.
32+
* **Agent ID**: You need an `agent_id` to connect to. You can either:
33+
* Create a new agent by following the
34+
[Gemini API Agents documentation](https://ai.google.dev/gemini-api/docs/agents).
35+
* Use an out-of-the-box agent ID, such as `antigravity-preview-05-2026`,
36+
which is commonly used in our examples.
37+
38+
### Option 2: Gemini Enterprise Agents Platform (GEAP) Backend
39+
40+
* **Authentication**: GEAP (formerly Vertex) requires Google Cloud
41+
credentials. Follow the
42+
[GEAP setup instructions](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/managed-agents/create-manage#before-you-begin)
43+
to authenticate your local environment (e.g., using `gcloud auth
44+
application-default login`).
45+
* **Agent ID**: Similar to the Gemini API, you need an `agent_id`. You can
46+
either:
47+
* Create a new agent via the
48+
[GEAP Managed Agents guide](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/managed-agents).
49+
* Use an out-of-the-box agent ID if available to your project.
50+
51+
## Get started
52+
53+
Here is a minimal implementation of `ManagedAgent` demonstrating its use.
54+
55+
```python
56+
import os
57+
from google.adk.agents import ManagedAgent
58+
from google.adk.tools import google_search
59+
from google.genai import types
60+
61+
# Ensure you have the MANAGED_AGENT_ID and the proper environment config
62+
_AGENT_ID = os.environ.get('MANAGED_AGENT_ID', 'antigravity-preview-05-2026')
63+
64+
managed_search_agent = ManagedAgent(
65+
name='managed_search_agent',
66+
description='Answers questions that need fresh, grounded information from the web.',
67+
agent_id=_AGENT_ID,
68+
environment={'type': 'remote'},
69+
tools=[google_search],
70+
)
71+
72+
# A managed code execution agent using raw types.Tool
73+
managed_code_execution_agent = ManagedAgent(
74+
name='managed_code_execution_agent',
75+
description='Solves computational questions by running code server-side.',
76+
agent_id=_AGENT_ID,
77+
environment={'type': 'remote'},
78+
tools=[types.Tool(code_execution=types.ToolCodeExecution())],
79+
)
80+
```
81+
82+
To see an orchestrator pattern using this code, you could wrap them using
83+
`AgentTool`:
84+
85+
```python
86+
from google.adk.agents import LlmAgent
87+
from google.adk.tools.agent_tool import AgentTool
88+
89+
# The local coordinator delegates tasks to the server-backed agents
90+
root_agent = LlmAgent(
91+
name='managed_tool_coordinator',
92+
description='Calls managed specialists as tools and composes the answer.',
93+
tools=[
94+
AgentTool(agent=managed_search_agent),
95+
AgentTool(agent=managed_code_execution_agent),
96+
],
97+
)
98+
```
99+
100+
## How it works
101+
102+
The `ManagedAgent` implements the `BaseAgent` contract but bypasses standard
103+
`generate_content` calls, instead sending interactions via
104+
`_create_interactions` with `background=True`. It natively streams partial
105+
events and terminal events in real-time back to the ADK `Runner` or parent flow.
106+
107+
When using the GEAP backend, it enforces a connection to the `global` location
108+
since the Managed Agents API is solely available globally. Because it runs
109+
remotely, tools are translated into standard `ToolParam` formats for
110+
interactions; any raw `google.genai.types.Tool` configs are passed through to
111+
the backend, enabling server-side code execution or remote google search
112+
seamlessly.
113+
114+
### State: local session vs. remote
115+
116+
`ManagedAgent` keeps almost no state locally. The ADK session only persists two
117+
values on the events it emits: the `previous_interaction_id` and the sandbox
118+
`environment_id`. On each new turn the agent recovers both by scanning prior
119+
session events, then reuses them so the conversation and its sandbox continue.
120+
121+
Everything else lives server-side. The Managed Agents API owns the sandbox
122+
environment and the full interaction history, and that remote interaction — not
123+
the local session — is the source of truth for continuing a conversation.
124+
Response text appears in both places (the local ADK events and the remote
125+
interaction history), but ADK stores only the ids it needs to recover and reuse
126+
the remote state; it never re-sends prior turns.
127+
128+
## Advanced applications
129+
130+
### Tool encapsulation for orchestration
131+
132+
* **Problem solved**: Sometimes a single LLM request needs to compose results
133+
from multiple independent, robust specialists without losing control of the
134+
execution turn.
135+
* **Implementation**: Encapsulate each `ManagedAgent` instance within its own
136+
separate `AgentTool` and provide them as a list of tools to an `LlmAgent`
137+
coordinator. The coordinator will invoke the managed agents (which run their
138+
sandboxed logic server-side), collect the results, and then compose the
139+
final synthesized response natively.
140+
141+
## Limitations
142+
143+
* **Location pinned (GEAP only)**: For the GEAP backend, the Managed Agents
144+
API is currently only served from the `global` location. Enterprise clients
145+
using regional endpoints will raise an error.
146+
* **Server-side tools only**: Client-executed tools (Python functions,
147+
callables) and MCP tools are not supported. Providing these will raise a
148+
`NotImplementedError`.
149+
* **Streaming only**: The agent only supports streaming interactions.
150+
Background-polling execution or strictly non-streaming connections are not
151+
yet fully supported (it natively uses `stream=True` and yields events).
152+
153+
## Related samples
154+
155+
* [Managed Agent Basic](../../../../contributing/samples/managed_agent/basic)
156+
* [Managed Agent Code Execution](../../../../contributing/samples/managed_agent/code_execution)

0 commit comments

Comments
 (0)