diff --git a/contributing/samples/managed_agent/single_turn/README.md b/contributing/samples/managed_agent/single_turn/README.md new file mode 100644 index 00000000..3c1198af --- /dev/null +++ b/contributing/samples/managed_agent/single_turn/README.md @@ -0,0 +1,69 @@ +# Managed Agent — Single-Turn Sub-Agent (Tool) Flow + +> For setup, authentication, backends, and background on `ManagedAgent`, see the +> [ManagedAgent guide](../../../../docs/guides/agents/managed_agent/index.md). + +## Overview + +This sample shows a local `LlmAgent` coordinator that calls two server-backed +`ManagedAgent` specialists as single-turn sub-agents (`mode='single_turn'`). +ADK auto-exposes each single-turn sub-agent to the coordinator as an inline tool. +The coordinator calls a specialist, receives the result, and may call several +specialists in one turn before composing the final answer itself. + +A single-turn sub-agent's internal events (e.g. tool calls) are preserved in the +shared session history. + +The two specialists are: + +- `managed_search_agent` — a `ManagedAgent` with the server-side `google_search` + tool, for questions that require web search results. +- `managed_code_execution_agent` — a `ManagedAgent` with server-side code + execution, for questions that require computation. + +> [!NOTE] +> Each `ManagedAgent` sets a `description`; ADK builds the tool declaration from +> it, so a missing description makes tool selection unreliable. + +> [!NOTE] +> Each single-turn call is stateless and isolated, so the coordinator should +> pass a self-contained request to each specialist (do not rely on a specialist +> remembering a previous call). + +## Sample Inputs + +- `What was the score of the most recent FIFA World Cup final?` + + Requires web search results — the coordinator calls `managed_search_agent`. + +- `What's the 30th Fibonacci number? Use code.` + + Requires computation — the coordinator calls `managed_code_execution_agent` + (answer: 832040). + +- `Look up the height of Mount Everest in meters, then use code to convert it to feet.` + + The coordinator calls both specialists in one turn (search for the height, + then code to multiply by 3.28084) and composes a single answer. + +## Graph + +```mermaid +graph TD + Coordinator[LlmAgent coordinator] -->|single_turn tool call| Search[managed_search_agent] + Coordinator -->|single_turn tool call| Code[managed_code_execution_agent] +``` + +## How To + +- Coordinator: an `LlmAgent` with a non-empty `sub_agents` list of single-turn + specialists. +- Specialists: each is a `ManagedAgent` with `mode='single_turn'`, an + `agent_id`, an `environment` spec, server-side `tools`, and a `description` + used for tool selection. +- Delegation: ADK exposes each single-turn specialist as an inline tool; the + coordinator calls it, gets the result, and keeps control of the turn. + +## Related Guides + +- [LlmAgent Single-Turn Mode](../../../../docs/guides/agents/llm_agent/single_turn.md) diff --git a/contributing/samples/managed_agent/single_turn/__init__.py b/contributing/samples/managed_agent/single_turn/__init__.py new file mode 100644 index 00000000..4015e47d --- /dev/null +++ b/contributing/samples/managed_agent/single_turn/__init__.py @@ -0,0 +1,15 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from . import agent diff --git a/contributing/samples/managed_agent/single_turn/agent.py b/contributing/samples/managed_agent/single_turn/agent.py new file mode 100644 index 00000000..085397bb --- /dev/null +++ b/contributing/samples/managed_agent/single_turn/agent.py @@ -0,0 +1,100 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""A coordinator LlmAgent that calls ManagedAgent specialists as single-turn tools. + +This sample shows a local ``LlmAgent`` orchestrating two server-backed +``ManagedAgent`` specialists exposed as single-turn sub-agents +(``mode='single_turn'``). ADK auto-wraps each single-turn sub-agent as an inline +tool: the coordinator calls a specialist like a tool, receives the result, and +may call several specialists within a single turn before composing the final +answer. The specialists' internal events are preserved in the shared session. + +Each managed call is stateless: single-turn runs are isolated, so the +coordinator should pass a self-contained request to each specialist. + +Two specialists are configured: + +- ``managed_search_agent`` -- a ``ManagedAgent`` with the server-side + ``google_search`` tool, for questions that require web search results. +- ``managed_code_execution_agent`` -- a ``ManagedAgent`` with server-side code + execution, for questions that require computation. + +Run with ``adk web`` / +``adk run contributing/samples/managed_agent/single_turn``. See the README +for the required environment / auth setup. +""" + +import os + +from google.adk.agents import LlmAgent +from google.adk.agents import ManagedAgent +from google.adk.tools import google_search +from google.genai import types + +# The Managed Agent id served by the Managed Agents API. Override with the +# MANAGED_AGENT_ID environment variable if your project has access to a +# different agent. +_DEFAULT_AGENT_ID = 'antigravity-preview-05-2026' +_AGENT_ID = os.environ.get('MANAGED_AGENT_ID', _DEFAULT_AGENT_ID) + +# A ManagedAgent specialist for questions that require web search results. +# mode='single_turn' exposes it to the coordinator as an inline tool. +managed_search_agent = ManagedAgent( + name='managed_search_agent', + mode='single_turn', + description=( + 'Answers questions that require up-to-date information from the web.' + ' Uses server-side Google Search.' + ), + agent_id=_AGENT_ID, + environment={'type': 'remote'}, + tools=[google_search], +) + +# A ManagedAgent specialist that solves computational questions by running code +# server-side. mode='single_turn' exposes it to the coordinator as an inline +# tool. +managed_code_execution_agent = ManagedAgent( + name='managed_code_execution_agent', + mode='single_turn', + description=( + 'Solves computational, math, or data questions by writing and running' + ' code server-side. Use for arithmetic, numeric, and other tasks best' + ' handled by executing code.' + ), + agent_id=_AGENT_ID, + environment={'type': 'remote'}, + tools=[types.Tool(code_execution=types.ToolCodeExecution())], +) + +# The local coordinator. No `model` is set, so ADK uses the default model. The +# two managed specialists are single-turn sub-agents, so ADK exposes each as an +# inline tool; the coordinator calls them and keeps control of the turn (it can +# call both before answering). +root_agent = LlmAgent( + name='managed_tool_coordinator', + description='Calls managed specialists as tools and composes the answer.', + instruction=( + 'You are an assistant with two specialist tools.\n' + '- Use `managed_search_agent` to look up current information from the' + ' web.\n' + '- Use `managed_code_execution_agent` to compute results by running' + ' code.\n' + 'You may call both tools in a single turn -- for example, look up a' + ' value and then compute with it -- and then write the final answer' + ' yourself.' + ), + sub_agents=[managed_search_agent, managed_code_execution_agent], +)