chore: import upstream snapshot with attribution

contributing/samples/multi_agent/sub_agents/README.md

@@ -0,0 +1,72 @@
+# ADK Agent Sub-Agents Sample
+
+## Overview
+
+This sample demonstrates how to create a hierarchical agent setup using sub-agents in the **ADK** framework, and also showcases how to use tool confirmation.
+
+It defines a root `Agent` named `sub_agents` that coordinates two sub-agents: `info_agent` and `close_agent`.
+
+- `info_agent` is equipped with a tool to check account status.
+- `close_agent` is equipped with a tool to close accounts, which requires user confirmation before execution.
+
+The root agent delegates tasks to these sub-agents based on the user's prompt. This sample illustrates how to modularize capabilities into separate agents instead of combining all tools on a single agent.
+
+## Sample Inputs
+
+- `Check the status of account ACC-123.`
+
+- `Close account ACC-123.`
+
+- `Check if account ACC-123 is active, and if so, close it.`
+
+## Graph
+
+```mermaid
+graph TD
+    sub_agents[Agent: sub_agents] --> info_agent[Agent: info_agent]
+    sub_agents --> close_agent[Agent: close_agent]
+    info_agent --> get_account_status[Tool: get_account_status]
+    close_agent --> close_account[Tool: close_account <br/>requires confirmation]
+```
+
+## How To
+
+1. Define the specific tools for each sub-agent:
+
+   ```python
+   def get_account_status(account_id: str) -> str:
+       """Gets the status of a bank account."""
+       return f"Account {account_id} is active."
+
+   def close_account(account_id: str) -> str:
+       """Closes a bank account."""
+       return f"Account {account_id} has been closed."
+   ```
+
+1. Register tools to their respective sub-agents, using `FunctionTool` for confirmation:
+
+   ```python
+   from google.adk.agents import Agent
+   from google.adk.tools.function_tool import FunctionTool
+
+   info_agent = Agent(
+       name="info_agent",
+       description="An agent that can check account status.",
+       tools=[get_account_status],
+   )
+
+   close_agent = Agent(
+       name="close_agent",
+       description="An agent that can close accounts.",
+       tools=[FunctionTool(func=close_account, require_confirmation=True)],
+   )
+   ```
+
+1. Add the sub-agents to the root agent's `sub_agents` list:
+
+   ```python
+   root_agent = Agent(
+       name="sub_agents",
+       sub_agents=[info_agent, close_agent],
+   )
+   ```

contributing/samples/multi_agent/sub_agents/__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/multi_agent/sub_agents/agent.py

@@ -0,0 +1,64 @@
+# 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 __future__ import annotations
+
+from google.adk.agents import Agent
+from google.adk.tools.function_tool import FunctionTool
+
+
+def get_account_status(account_id: str) -> str:
+  """Gets the status of a bank account.
+
+  Args:
+      account_id: The account ID to check.
+
+  Returns:
+      The status of the account.
+  """
+  return f"Account {account_id} is active."
+
+
+def close_account(account_id: str) -> str:
+  """Closes a bank account. This action requires user confirmation.
+
+  Args:
+      account_id: The account ID to close.
+
+  Returns:
+      A confirmation message.
+  """
+  return f"Account {account_id} has been closed."
+
+
+info_agent = Agent(
+    name="info_agent",
+    description="An agent that can check account status.",
+    tools=[get_account_status],
+)
+
+close_agent = Agent(
+    name="close_agent",
+    description="An agent that can close accounts.",
+    tools=[FunctionTool(func=close_account, require_confirmation=True)],
+)
+
+root_agent = Agent(
+    name="sub_agents",
+    description=(
+        "A root agent that can check accounts and close them by delegating to"
+        " sub-agents."
+    ),
+    sub_agents=[info_agent, close_agent],
+)

contributing/samples/multi_agent/sub_agents/tests/check_and_close.json

@@ -0,0 +1,315 @@
+{
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "Check if account ACC-123 is active, and if so, close it."
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "author": "sub_agents",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {
+                "agent_name": "info_agent"
+              },
+              "id": "fc-1",
+              "name": "transfer_to_agent"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "longRunningToolIds": [],
+      "nodeInfo": {
+        "path": "sub_agents@1"
+      }
+    },
+    {
+      "actions": {
+        "transferToAgent": "info_agent"
+      },
+      "author": "sub_agents",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-1",
+              "name": "transfer_to_agent",
+              "response": {
+                "result": null
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-3",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "sub_agents@1"
+      }
+    },
+    {
+      "author": "info_agent",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {
+                "account_id": "ACC-123"
+              },
+              "id": "fc-2",
+              "name": "get_account_status"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-4",
+      "invocationId": "i-1",
+      "longRunningToolIds": [],
+      "nodeInfo": {
+        "path": "sub_agents@1/info_agent@1"
+      }
+    },
+    {
+      "author": "info_agent",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-2",
+              "name": "get_account_status",
+              "response": {
+                "result": "Account ACC-123 is active."
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-5",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "sub_agents@1/info_agent@1"
+      }
+    },
+    {
+      "author": "info_agent",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {
+                "agent_name": "close_agent"
+              },
+              "id": "fc-3",
+              "name": "transfer_to_agent"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-6",
+      "invocationId": "i-1",
+      "longRunningToolIds": [],
+      "nodeInfo": {
+        "path": "sub_agents@1/info_agent@1"
+      }
+    },
+    {
+      "actions": {
+        "transferToAgent": "close_agent"
+      },
+      "author": "info_agent",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-3",
+              "name": "transfer_to_agent",
+              "response": {
+                "result": null
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-7",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "sub_agents@1/info_agent@1"
+      }
+    },
+    {
+      "author": "close_agent",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {
+                "account_id": "ACC-123"
+              },
+              "id": "fc-4",
+              "name": "close_account"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-8",
+      "invocationId": "i-1",
+      "longRunningToolIds": [],
+      "nodeInfo": {
+        "path": "sub_agents@1/close_agent@1"
+      }
+    },
+    {
+      "author": "close_agent",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {
+                "originalFunctionCall": {
+                  "args": {
+                    "account_id": "ACC-123"
+                  },
+                  "id": "fc-4",
+                  "name": "close_account"
+                },
+                "toolConfirmation": {
+                  "confirmed": false,
+                  "hint": "Please approve or reject the tool call close_account() by responding with a FunctionResponse with an expected ToolConfirmation payload."
+                }
+              },
+              "id": "fc-5",
+              "name": "adk_request_confirmation"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "id": "e-9",
+      "invocationId": "i-1",
+      "longRunningToolIds": [
+        "fc-5"
+      ],
+      "nodeInfo": {
+        "path": "sub_agents@1/close_agent@1"
+      }
+    },
+    {
+      "actions": {
+        "requestedToolConfirmations": {
+          "fc-4": {
+            "confirmed": false,
+            "hint": "Please approve or reject the tool call close_account() by responding with a FunctionResponse with an expected ToolConfirmation payload."
+          }
+        },
+        "skipSummarization": true
+      },
+      "author": "close_agent",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-4",
+              "name": "close_account",
+              "response": {
+                "error": "This tool call requires confirmation, please approve or reject."
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-10",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "sub_agents@1/close_agent@1"
+      }
+    },
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-5",
+              "name": "adk_request_confirmation",
+              "response": {
+                "confirmed": true
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-11",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "author": "close_agent",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-4",
+              "name": "close_account",
+              "response": {
+                "result": "Account ACC-123 has been closed."
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-12",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "sub_agents@1/close_agent@1"
+      }
+    },
+    {
+      "author": "close_agent",
+      "content": {
+        "parts": [
+          {
+            "text": "Account ACC-123 has been closed."
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-13",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "sub_agents@1/close_agent@1"
+      }
+    }
+  ]
+}

contributing/samples/multi_agent/sub_agents/tests/check_status.json

@@ -0,0 +1,132 @@
+{
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "Check the status of account ACC-123"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "author": "sub_agents",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {
+                "agent_name": "info_agent"
+              },
+              "id": "fc-1",
+              "name": "transfer_to_agent"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "longRunningToolIds": [],
+      "nodeInfo": {
+        "path": "sub_agents@1"
+      }
+    },
+    {
+      "actions": {
+        "transferToAgent": "info_agent"
+      },
+      "author": "sub_agents",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-1",
+              "name": "transfer_to_agent",
+              "response": {
+                "result": null
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-3",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "sub_agents@1"
+      }
+    },
+    {
+      "author": "info_agent",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {
+                "account_id": "ACC-123"
+              },
+              "id": "fc-2",
+              "name": "get_account_status"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-4",
+      "invocationId": "i-1",
+      "longRunningToolIds": [],
+      "nodeInfo": {
+        "path": "sub_agents@1/info_agent@1"
+      }
+    },
+    {
+      "author": "info_agent",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-2",
+              "name": "get_account_status",
+              "response": {
+                "result": "Account ACC-123 is active."
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-5",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "sub_agents@1/info_agent@1"
+      }
+    },
+    {
+      "author": "info_agent",
+      "content": {
+        "parts": [
+          {
+            "text": "Account ACC-123 is active."
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-6",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "sub_agents@1/info_agent@1"
+      }
+    }
+  ]
+}