Skip to content

Commit 57e1ba6

Browse files
haranrkcopybara-github
haranrk
authored and
copybara-github
committed
docs(samples): Add ManagedAgent single-turn sub-agent sample
Add a runnable sample under contributing/samples/managed_agent/single_turn showing a local LlmAgent coordinator that calls two server-backed ManagedAgent specialists (server-side google_search and code execution) as single-turn sub-agents (mode='single_turn'). ADK auto-wraps each single-turn sub-agent as an inline tool, so the coordinator stays in control and can call both specialists within one turn; unlike AgentTool, the specialists' internal events are preserved in the shared session. The sample exposes a root_agent in agent.py and ships a README covering setup and example prompts. Co-authored-by: Haran Rajkumar <haranrk@google.com> PiperOrigin-RevId: 945969891
1 parent 26ed6fe commit 57e1ba6

3 files changed

Lines changed: 184 additions & 0 deletions

File tree

‎contributing/samples/managed_agent/single_turn/README.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Managed Agent — Single-Turn Sub-Agent (Tool) Flow
2+
3+
> For setup, authentication, backends, and background on `ManagedAgent`, see the
4+
> [ManagedAgent guide](../../../../docs/guides/agents/managed_agent/index.md).
5+
6+
## Overview
7+
8+
This sample shows a local `LlmAgent` coordinator that calls two server-backed
9+
`ManagedAgent` specialists as single-turn sub-agents (`mode='single_turn'`).
10+
ADK auto-exposes each single-turn sub-agent to the coordinator as an inline tool.
11+
The coordinator calls a specialist, receives the result, and may call several
12+
specialists in one turn before composing the final answer itself.
13+
14+
A single-turn sub-agent's internal events (e.g. tool calls) are preserved in the
15+
shared session history.
16+
17+
The two specialists are:
18+
19+
- `managed_search_agent` — a `ManagedAgent` with the server-side `google_search`
20+
tool, for questions that require web search results.
21+
- `managed_code_execution_agent` — a `ManagedAgent` with server-side code
22+
execution, for questions that require computation.
23+
24+
> [!NOTE]
25+
> Each `ManagedAgent` sets a `description`; ADK builds the tool declaration from
26+
> it, so a missing description makes tool selection unreliable.
27+
28+
> [!NOTE]
29+
> Each single-turn call is stateless and isolated, so the coordinator should
30+
> pass a self-contained request to each specialist (do not rely on a specialist
31+
> remembering a previous call).
32+
33+
## Sample Inputs
34+
35+
- `What was the score of the most recent FIFA World Cup final?`
36+
37+
Requires web search results — the coordinator calls `managed_search_agent`.
38+
39+
- `What's the 30th Fibonacci number? Use code.`
40+
41+
Requires computation — the coordinator calls `managed_code_execution_agent`
42+
(answer: 832040).
43+
44+
- `Look up the height of Mount Everest in meters, then use code to convert it to feet.`
45+
46+
The coordinator calls both specialists in one turn (search for the height,
47+
then code to multiply by 3.28084) and composes a single answer.
48+
49+
## Graph
50+
51+
```mermaid
52+
graph TD
53+
Coordinator[LlmAgent coordinator] -->|single_turn tool call| Search[managed_search_agent]
54+
Coordinator -->|single_turn tool call| Code[managed_code_execution_agent]
55+
```
56+
57+
## How To
58+
59+
- Coordinator: an `LlmAgent` with a non-empty `sub_agents` list of single-turn
60+
specialists.
61+
- Specialists: each is a `ManagedAgent` with `mode='single_turn'`, an
62+
`agent_id`, an `environment` spec, server-side `tools`, and a `description`
63+
used for tool selection.
64+
- Delegation: ADK exposes each single-turn specialist as an inline tool; the
65+
coordinator calls it, gets the result, and keeps control of the turn.
66+
67+
## Related Guides
68+
69+
- [LlmAgent Single-Turn Mode](../../../../docs/guides/agents/llm_agent/single_turn.md)

‎contributing/samples/managed_agent/single_turn/__init__.py‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Copyright 2026 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
from . import agent

‎contributing/samples/managed_agent/single_turn/agent.py‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Copyright 2026 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
"""A coordinator LlmAgent that calls ManagedAgent specialists as single-turn tools.
16+
17+
This sample shows a local ``LlmAgent`` orchestrating two server-backed
18+
``ManagedAgent`` specialists exposed as single-turn sub-agents
19+
(``mode='single_turn'``). ADK auto-wraps each single-turn sub-agent as an inline
20+
tool: the coordinator calls a specialist like a tool, receives the result, and
21+
may call several specialists within a single turn before composing the final
22+
answer. The specialists' internal events are preserved in the shared session.
23+
24+
Each managed call is stateless: single-turn runs are isolated, so the
25+
coordinator should pass a self-contained request to each specialist.
26+
27+
Two specialists are configured:
28+
29+
- ``managed_search_agent`` -- a ``ManagedAgent`` with the server-side
30+
``google_search`` tool, for questions that require web search results.
31+
- ``managed_code_execution_agent`` -- a ``ManagedAgent`` with server-side code
32+
execution, for questions that require computation.
33+
34+
Run with ``adk web`` /
35+
``adk run contributing/samples/managed_agent/single_turn``. See the README
36+
for the required environment / auth setup.
37+
"""
38+
39+
import os
40+
41+
from google.adk.agents import LlmAgent
42+
from google.adk.agents import ManagedAgent
43+
from google.adk.tools import google_search
44+
from google.genai import types
45+
46+
# The Managed Agent id served by the Managed Agents API. Override with the
47+
# MANAGED_AGENT_ID environment variable if your project has access to a
48+
# different agent.
49+
_DEFAULT_AGENT_ID = 'antigravity-preview-05-2026'
50+
_AGENT_ID = os.environ.get('MANAGED_AGENT_ID', _DEFAULT_AGENT_ID)
51+
52+
# A ManagedAgent specialist for questions that require web search results.
53+
# mode='single_turn' exposes it to the coordinator as an inline tool.
54+
managed_search_agent = ManagedAgent(
55+
name='managed_search_agent',
56+
mode='single_turn',
57+
description=(
58+
'Answers questions that require up-to-date information from the web.'
59+
' Uses server-side Google Search.'
60+
),
61+
agent_id=_AGENT_ID,
62+
environment={'type': 'remote'},
63+
tools=[google_search],
64+
)
65+
66+
# A ManagedAgent specialist that solves computational questions by running code
67+
# server-side. mode='single_turn' exposes it to the coordinator as an inline
68+
# tool.
69+
managed_code_execution_agent = ManagedAgent(
70+
name='managed_code_execution_agent',
71+
mode='single_turn',
72+
description=(
73+
'Solves computational, math, or data questions by writing and running'
74+
' code server-side. Use for arithmetic, numeric, and other tasks best'
75+
' handled by executing code.'
76+
),
77+
agent_id=_AGENT_ID,
78+
environment={'type': 'remote'},
79+
tools=[types.Tool(code_execution=types.ToolCodeExecution())],
80+
)
81+
82+
# The local coordinator. No `model` is set, so ADK uses the default model. The
83+
# two managed specialists are single-turn sub-agents, so ADK exposes each as an
84+
# inline tool; the coordinator calls them and keeps control of the turn (it can
85+
# call both before answering).
86+
root_agent = LlmAgent(
87+
name='managed_tool_coordinator',
88+
description='Calls managed specialists as tools and composes the answer.',
89+
instruction=(
90+
'You are an assistant with two specialist tools.\n'
91+
'- Use `managed_search_agent` to look up current information from the'
92+
' web.\n'
93+
'- Use `managed_code_execution_agent` to compute results by running'
94+
' code.\n'
95+
'You may call both tools in a single turn -- for example, look up a'
96+
' value and then compute with it -- and then write the final answer'
97+
' yourself.'
98+
),
99+
sub_agents=[managed_search_agent, managed_code_execution_agent],
100+
)

0 commit comments

Comments
 (0)