chore: import upstream snapshot with attribution

contributing/samples/managed_agent/basic/README.md

@@ -0,0 +1,50 @@
+# Managed Agent
+
+> For setup, authentication, backends, and background on `ManagedAgent`, see the
+> [ManagedAgent guide](../../../../docs/guides/agents/managed_agent/index.md).
+
+## Overview
+
+This sample runs a `ManagedAgent` configured with the built-in `google_search`
+tool. Given an open-ended request, the server-side harness autonomously issues
+many searches and synthesizes the result in a single turn.
+
+## Sample Inputs
+
+- `Compare the current flagship smartphones from Apple, Samsung, and Google. For each, find its launch price, display size, and main rear camera resolution, then recommend the best value for someone who mostly takes photos.`
+
+  The showcase input. A single question the harness answers by fanning out into a
+  dozen-odd searches. It does broad discovery first, then targeted per-model spec
+  and price lookups, self-correcting when it hits a stale model, before composing
+  a comparison table and a reasoned recommendation.
+
+- `Which of those would you pick for shooting video instead?`
+
+  A follow-up turn that reuses the recovered remote sandbox and the previous
+  interaction, continuing the same research thread. This demonstrates multi-turn
+  chaining.
+
+## Graph
+
+```mermaid
+graph LR
+    User -->|message| ManagedAgent
+    ManagedAgent -->|interactions.create| ManagedAgentsAPI
+    ManagedAgentsAPI -->|server-side research loop: google_search ×N| ManagedAgentsAPI
+    ManagedAgentsAPI -->|streamed events| ManagedAgent
+    ManagedAgent -->|answer| User
+```
+
+## How To
+
+- **Create the agent**: instantiate `ManagedAgent` with an `agent_id`, an
+  `environment` spec, and a list of server-side `tools`. No `model` is set; the
+  model is part of the managed agent on the server.
+- **Provision a sandbox**: `environment={'type': 'remote'}` requests a fresh
+  remote sandbox. The resulting environment id is stored on emitted events, so
+  subsequent turns automatically recover and reuse it.
+- **Multi-turn chaining**: the agent recovers the `previous_interaction_id` from
+  the session events, so follow-up turns continue the same interaction without
+  any extra wiring.
+- **Drive it**: a `ManagedAgent` is a `BaseAgent`, so a standard `Runner` runs
+  it just like any other agent.

contributing/samples/managed_agent/basic/__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/basic/agent.py

@@ -0,0 +1,49 @@
+# 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 ManagedAgent backed by the Managed Agents API (interactions.create).
+
+``ManagedAgent`` calls the Managed Agents API directly from its run loop instead
+of running a local model loop. It currently supports server-side tools only
+(ADK built-in tools and raw ``google.genai.types.Tool`` configs); here we wire
+up ``google_search``, which runs entirely on the server.
+
+A fresh remote sandbox is provisioned via ``environment={'type': 'remote'}``;
+the environment id is recovered from prior events so multi-turn conversations
+reuse the same sandbox.
+
+Run with ``adk web`` / ``adk run contributing/samples/managed_agent/basic``. See
+the README for the required environment / auth setup.
+"""
+
+import os
+
+from google.adk.agents import ManagedAgent
+from google.adk.tools import google_search
+
+# 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'
+
+root_agent = ManagedAgent(
+    name='managed_search_agent',
+    agent_id=os.environ.get('MANAGED_AGENT_ID', _DEFAULT_AGENT_ID),
+    # Provision a remote sandbox for the agent. The environment id is recovered
+    # from prior events, so follow-up turns reuse the same sandbox.
+    environment={'type': 'remote'},
+    # Only server-side tools are supported today. google_search is an ADK
+    # built-in tool that executes on the server.
+    tools=[google_search],
+)

contributing/samples/managed_agent/code_execution/README.md

@@ -0,0 +1,57 @@
+# Managed Agent - Code Execution
+
+> For setup, authentication, backends, and background on `ManagedAgent`, see the
+> [ManagedAgent guide](../../../../docs/guides/agents/managed_agent/index.md).
+
+## Overview
+
+This sample runs a `ManagedAgent` configured with the built-in **code execution**
+tool so it can write and run code server-side to compute answers.
+
+Unlike a regular `LlmAgent` (which enables code execution via
+`code_executor=BuiltInCodeExecutor()`), `ManagedAgent` has no `code_executor`
+field. Instead you pass the raw built-in tool config
+`types.Tool(code_execution=types.ToolCodeExecution())` in `tools` -- the same
+config `BuiltInCodeExecutor` produces under the hood. This makes the sample a
+demonstration of the raw `types.Tool` server-side tool path.
+
+## Sample Inputs
+
+- `What is the sum of the first 50 prime numbers? Use code to compute it.`
+
+  The model writes and runs code server-side; the answer (5117) comes from the
+  executed code rather than the model guessing.
+
+- `Now do the same for the first 100 primes.`
+
+  A follow-up turn that reuses the recovered remote sandbox and the previous
+  interaction (answer: 24133), demonstrating multi-turn chaining.
+
+## Graph
+
+```mermaid
+graph LR
+    User -->|message| ManagedAgent
+    ManagedAgent -->|interactions.create| ManagedAgentsAPI
+    ManagedAgentsAPI -->|server-side code execution| ManagedAgentsAPI
+    ManagedAgentsAPI -->|streamed events| ManagedAgent
+    ManagedAgent -->|answer| User
+```
+
+## How To
+
+- **Create the agent**: instantiate `ManagedAgent` with an `agent_id`, an
+  `environment` spec, and
+  `tools=[types.Tool(code_execution=types.ToolCodeExecution())]`. No `model` is
+  set -- the model is part of the managed agent on the server.
+- **Enable code execution**: `ManagedAgent` has no `code_executor` field, so the
+  raw `types.Tool(code_execution=...)` config is passed in `tools`. The
+  interactions converter turns it into the server-side `code_execution` tool.
+- **Provision a sandbox**: `environment={'type': 'remote'}` requests a fresh
+  remote sandbox. The resulting environment id is stored on emitted events, so
+  subsequent turns automatically recover and reuse it.
+- **Multi-turn chaining**: the agent recovers the `previous_interaction_id` from
+  the session events, so follow-up turns continue the same interaction without
+  any extra wiring.
+- **Drive it**: a `ManagedAgent` is a `BaseAgent`, so a standard `Runner` runs
+  it just like any other agent.

contributing/samples/managed_agent/code_execution/__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/code_execution/agent.py

@@ -0,0 +1,55 @@
+# 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 ManagedAgent that runs server-side code execution.
+
+``ManagedAgent`` calls the Managed Agents API directly from its run loop instead
+of running a local model loop. It currently supports server-side tools only.
+
+Unlike ``LlmAgent``, ``ManagedAgent`` has no ``code_executor`` field, so code
+execution is enabled by passing the raw built-in tool config
+``types.Tool(code_execution=types.ToolCodeExecution())`` in ``tools`` -- the
+same config ``BuiltInCodeExecutor`` produces under the hood. The model writes
+and runs code on the server to compute answers.
+
+A fresh remote sandbox is provisioned via ``environment={'type': 'remote'}``;
+the environment id is recovered from prior events so multi-turn conversations
+reuse the same sandbox.
+
+Run with ``adk web`` /
+``adk run contributing/samples/managed_agent/code_execution``. See the README
+for the required environment / auth setup.
+"""
+
+import os
+
+from google.adk.agents import ManagedAgent
+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'
+
+root_agent = ManagedAgent(
+    name='managed_code_execution_agent',
+    agent_id=os.environ.get('MANAGED_AGENT_ID', _DEFAULT_AGENT_ID),
+    # Provision a remote sandbox for the agent. The environment id is recovered
+    # from prior events, so follow-up turns reuse the same sandbox.
+    environment={'type': 'remote'},
+    # ManagedAgent has no `code_executor` field; enable server-side code
+    # execution by passing the raw built-in tool config. This is the same config
+    # BuiltInCodeExecutor appends for a regular LlmAgent.
+    tools=[types.Tool(code_execution=types.ToolCodeExecution())],
+)

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