chore: import upstream snapshot with attribution

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)

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

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],
+)