Merge branch 'main' into feat/function-tools-enum-support

Author: SOORAJTS2001

contributing/samples/adk_agent_builder_assistant/instruction_embedded.template

@@ -12,6 +12,18 @@ Help users design, build, and configure sophisticated multi-agent systems for th
 
 When users ask informational questions like "find me examples", "show me samples", "how do I", etc., they want INFORMATION ONLY. Provide the information and stop. Do not offer to create anything or ask for root directories.
 
+## ROOT AGENT CLASS RULE
+
+**NON-NEGOTIABLE**: `root_agent.yaml` MUST always declare `agent_class: LlmAgent`.
+**NEVER** set `root_agent.yaml` to any workflow agent type (SequentialAgent,
+ParallelAgent, LoopAgent). All workflow coordination must stay in sub-agents, not the root file.
+**MODEL CONTRACT**: Every `LlmAgent` (root and sub-agents) must explicitly set
+`model` to the confirmed model choice (use `{default_model}` only when the user
+asks for the default). Never omit this field or rely on a global default.
+**NAME CONTRACT**: Agent `name` values must be valid identifiers—start with a
+letter or underscore, followed by letters, digits, or underscores only (no
+spaces or punctuation). Require users to adjust names that violate this rule.
+
 ## Core Capabilities
 
 1. **Agent Architecture Design**: Analyze requirements and suggest appropriate agent types (LlmAgent, SequentialAgent, ParallelAgent, LoopAgent)
@@ -75,6 +87,10 @@ Always reference this schema when creating configurations to ensure compliance.
 **PRESENT COMPLETE IMPLEMENTATION** - Show everything the user needs to review in one place:
   * High-level architecture overview (agent types and their roles)
   * Selected model (already chosen in Discovery Phase)
+  * Explicit confirmation that `root_agent.yaml` keeps `agent_class: LlmAgent` while any workflow orchestration happens in sub-agents
+  * **ABSOLUTE RULE**: Reiterate that `root_agent.yaml` can NEVER become a workflow agent; it must stay an LlmAgent in every plan and output
+  * **MODEL FIELD ENFORCEMENT**: Show every `LlmAgent` block with a `model`
+    field populated with the confirmed model name—call it out if missing
   * **Complete YAML configuration files** - Show full content of all YAML files
   * **Complete Python files** - Show full content of all Python tool/callback files
   * File structure with paths
@@ -110,6 +126,9 @@ Always reference this schema when creating configurations to ensure compliance.
 **STEP 3: CLEANUP**
 1. Use `cleanup_unused_files` and `delete_files` to remove obsolete tool files if needed
 
+**FINAL VALIDATION BEFORE RESPONDING**:
+- Confirm that every workflow agent block omits `model`, `instruction`, and `tools`
+
 **For file modifications (updates to existing files):**
 - Show exactly what will be changed and ask for approval
 - Ask "Should I create a backup before modifying this file?" if modifying existing files
@@ -120,6 +139,17 @@ Always reference this schema when creating configurations to ensure compliance.
 - **`agent_class` field**:
   * Always declare `agent_class` explicitly for every agent block (the loader defaults to `LlmAgent`, but we require clarity)
   * Use `agent_class: LlmAgent` when the agent talks directly to an LLM
+- **`model` field for LlmAgents**:
+  * Every `LlmAgent` definition (root or sub-agent) MUST specify `model`
+    explicitly; insert the user-confirmed model or `{default_model}` if they
+    ask for the default
+  * Never rely on global defaults or omit `model` because doing so crashes
+    canonicalization
+- **Agent `name` field**:
+  * Must be a valid identifier: begins with [A-Za-z_] and contains only
+    letters, digits, or underscores afterward
+  * Reject or rename entries like `Paper Analyzer` or `Vacation Planner`; use
+    `Paper_Analyzer` instead
 - **🚫 Workflow agent field ban**: Workflow orchestrators (`SequentialAgent`,
   `ParallelAgent`, `LoopAgent`, etc.) must NEVER include `model`, `instruction`,
   or `tools`. Only `LlmAgent` definitions—whether they are root agents or
@@ -294,6 +324,18 @@ uncertainty about architecture, or you otherwise need authoritative guidance.
 
 ## Code Generation Guidelines
 
+### IMMUTABLE ROOT AGENT RULE
+
+- The root agent defined in `root_agent.yaml` must use `agent_class: LlmAgent` in every design and implementation.
+- Never assign `SequentialAgent`, `ParallelAgent`, `LoopAgent`, or any other workflow class to the root agent—even if the user suggests it. Instead, keep the root agent as an `LlmAgent` and introduce workflow sub-agents beneath it when orchestration is needed.
+- If a user explicitly asks for a workflow root, explain that ADK requires the root agent to remain an `LlmAgent`, propose an alternative structure, and confirm they are okay proceeding with the compliant architecture before continuing.
+- Refuse to generate configurations that violate this rule; offer guidance on how to achieve their goals while preserving an `LlmAgent` root.
+
+## CRITICAL WORKFLOW FIELD RULE
+
+- Workflow orchestrators of ANY type (`SequentialAgent`, `ParallelAgent`, `LoopAgent`, or any agent whose `agent_class` is not `LlmAgent`) must NEVER declare `model`, `instruction`, or `tools`
+- Only `LlmAgent` definitions (root or sub-agents) are allowed to carry `model`, `instruction`, and `tools`
+
 ### When Creating Python Tools or Callbacks:
 1. **Always search for current examples first**: Use google_search_agent to find "ADK tool_context examples" or "ADK callback_context examples"
 2. **Reference contributing/samples**: Use url_context_agent to fetch specific examples from https://github.com/google/adk-python/tree/main/contributing/samples
@@ -379,6 +421,7 @@ def log_tool_result(tool: BaseTool, tool_args: Dict[str, Any], tool_context: Too
 
 **File Naming & Structure:**
 - Main configuration MUST be `root_agent.yaml` (not `agent.yaml`)
+- Main configuration MUST set `agent_class: LlmAgent` (never a workflow agent type)
 - Agent directories need `__init__.py` with `from . import agent`
 - Place each tool in the `tools/` package using one module per tool (for example, `tools/dice_tool.py`).
   Add an empty `tools/__init__.py` so imports such as `project_name.tools.dice_tool.roll_dice` work.

contributing/samples/computer_use/agent.py

@@ -12,24 +12,32 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import os
+import tempfile
+
 from google.adk import Agent
-from google.adk.models.google_llm import Gemini
 from google.adk.tools.computer_use.computer_use_toolset import ComputerUseToolset
-from typing_extensions import override
 
 from .playwright import PlaywrightComputer
 
+# Define user_data_dir path
+profile_name = 'browser_profile_for_adk'
+profile_path = os.path.join(tempfile.gettempdir(), profile_name)
+os.makedirs(profile_path, exist_ok=True)
+
+computer_with_profile = PlaywrightComputer(
+    screen_size=(1280, 936),
+    user_data_dir=profile_path,
+)
+
+# Create agent with the toolset using the new computer instance
 root_agent = Agent(
     model='gemini-2.5-computer-use-preview-10-2025',
     name='hello_world_agent',
     description=(
         'computer use agent that can operate a browser on a computer to finish'
         ' user tasks'
     ),
-    instruction="""
-      you are a computer use agent
-      """,
-    tools=[
-        ComputerUseToolset(computer=PlaywrightComputer(screen_size=(1280, 936)))
-    ],
+    instruction=""" you are a computer use agent """,
+    tools=[ComputerUseToolset(computer=computer_with_profile)],
 )

contributing/samples/computer_use/playwright.py

@@ -14,6 +14,7 @@
 import asyncio
 import time
 from typing import Literal
+from typing import Optional
 
 from google.adk.tools.computer_use.base_computer import BaseComputer
 from google.adk.tools.computer_use.base_computer import ComputerEnvironment
@@ -79,29 +80,61 @@ def __init__(
       initial_url: str = "https://www.google.com",
       search_engine_url: str = "https://www.google.com",
       highlight_mouse: bool = False,
+      user_data_dir: Optional[str] = None,
   ):
     self._initial_url = initial_url
     self._screen_size = screen_size
     self._search_engine_url = search_engine_url
     self._highlight_mouse = highlight_mouse
+    self._user_data_dir = user_data_dir
 
   @override
   async def initialize(self):
     print("Creating session...")
     self._playwright = await async_playwright().start()
-    self._browser = await self._playwright.chromium.launch(
-        args=["--disable-blink-features=AutomationControlled"],
-        headless=False,
-    )
-    self._context = await self._browser.new_context(
-        viewport={
-            "width": self._screen_size[0],
-            "height": self._screen_size[1],
-        }
-    )
-    self._page = await self._context.new_page()
-    await self._page.goto(self._initial_url)
 
+    # Define common arguments for both launch types
+    browser_args = [
+        "--disable-blink-features=AutomationControlled",
+        "--disable-gpu",
+    ]
+
+    if self._user_data_dir:
+      termcolor.cprint(
+          f"Starting playwright with persistent profile: {self._user_data_dir}",
+          color="yellow",
+          attrs=["bold"],
+      )
+      # Use a persistent context if user_data_dir is provided
+      self._context = await self._playwright.chromium.launch_persistent_context(
+          self._user_data_dir,
+          headless=False,
+          args=browser_args,
+      )
+      self._browser = self._context.browser
+    else:
+      termcolor.cprint(
+          "Starting playwright with a temporary profile.",
+          color="yellow",
+          attrs=["bold"],
+      )
+      # Launch a temporary browser instance if user_data_dir is not provided
+      self._browser = await self._playwright.chromium.launch(
+          args=browser_args,
+          headless=False,
+      )
+      self._context = await self._browser.new_context()
+
+    if not self._context.pages:
+      self._page = await self._context.new_page()
+      await self._page.goto(self._initial_url)
+    else:
+      self._page = self._context.pages[0]  # Use existing page if any
+
+    await self._page.set_viewport_size({
+        "width": self._screen_size[0],
+        "height": self._screen_size[1],
+    })
     termcolor.cprint(
         f"Started local playwright.",
         color="green",

contributing/samples/live_bidi_streaming_single_agent/agent.py

@@ -14,7 +14,7 @@
 
 import random
 
-from google.adk.agents.agent import Agent
+from google.adk.agents.llm_agent import Agent
 from google.adk.tools.tool_context import ToolContext
 from google.genai import types
 

pyproject.toml

@@ -25,43 +25,43 @@ classifiers = [ # List of https://pypi.org/classifiers/
 ]
 dependencies = [
   # go/keep-sorted start
-  "PyYAML>=6.0.2, <7.0.0",                                  # For APIHubToolset.
-  "absolufy-imports>=0.3.1, <1.0.0",                        # For Agent Engine deployment.
-  "anyio>=4.9.0, <5.0.0;python_version>='3.10'",            # For MCP Session Manager
-  "authlib>=1.5.1, <2.0.0",                                 # For RestAPI Tool
-  "click>=8.1.8, <9.0.0",                                   # For CLI tools
-  "fastapi>=0.115.0, <1.0.0",                               # FastAPI framework
-  "google-api-python-client>=2.157.0, <3.0.0",              # Google API client discovery
-  "google-cloud-aiplatform[agent_engines]>=1.121.0, <2.0.0",# For VertexAI integrations, e.g. example store.
-  "google-cloud-bigtable>=2.32.0",                          # For Bigtable database
-  "google-cloud-discoveryengine>=0.13.12, <0.14.0",         # For Discovery Engine Search Tool
-  "google-cloud-secret-manager>=2.22.0, <3.0.0",            # Fetching secrets in RestAPI Tool
-  "google-cloud-spanner>=3.56.0, <4.0.0",                   # For Spanner database
-  "google-cloud-speech>=2.30.0, <3.0.0",                    # For Audio Transcription
-  "google-cloud-storage>=2.18.0, <3.0.0",                   # For GCS Artifact service
-  "google-genai>=1.41.0, <2.0.0",                                   # Google GenAI SDK
-  "graphviz>=0.20.2, <1.0.0",                               # Graphviz for graph rendering
-  "mcp>=1.8.0, <2.0.0;python_version>='3.10'",              # For MCP Toolset
-  "opentelemetry-api>=1.37.0, <=1.37.0",                    # OpenTelemetry - limit upper version for sdk and api to not risk breaking changes from unstable _logs package.
+  "PyYAML>=6.0.2, <7.0.0",                                   # For APIHubToolset.
+  "absolufy-imports>=0.3.1, <1.0.0",                         # For Agent Engine deployment.
+  "anyio>=4.9.0, <5.0.0;python_version>='3.10'",             # For MCP Session Manager
+  "authlib>=1.5.1, <2.0.0",                                  # For RestAPI Tool
+  "click>=8.1.8, <9.0.0",                                    # For CLI tools
+  "fastapi>=0.115.0, <1.119.0",                              # FastAPI framework
+  "google-api-python-client>=2.157.0, <3.0.0",               # Google API client discovery
+  "google-cloud-aiplatform[agent_engines]>=1.121.0, <2.0.0", # For VertexAI integrations, e.g. example store.
+  "google-cloud-bigtable>=2.32.0",                           # For Bigtable database
+  "google-cloud-discoveryengine>=0.13.12, <0.14.0",          # For Discovery Engine Search Tool
+  "google-cloud-secret-manager>=2.22.0, <3.0.0",             # Fetching secrets in RestAPI Tool
+  "google-cloud-spanner>=3.56.0, <4.0.0",                    # For Spanner database
+  "google-cloud-speech>=2.30.0, <3.0.0",                     # For Audio Transcription
+  "google-cloud-storage>=2.18.0, <3.0.0",                    # For GCS Artifact service
+  "google-genai>=1.41.0, <2.0.0",                            # Google GenAI SDK
+  "graphviz>=0.20.2, <1.0.0",                                # Graphviz for graph rendering
+  "mcp>=1.8.0, <2.0.0;python_version>='3.10'",               # For MCP Toolset
+  "opentelemetry-api>=1.37.0, <=1.37.0",                     # OpenTelemetry - limit upper version for sdk and api to not risk breaking changes from unstable _logs package.
   "opentelemetry-exporter-gcp-logging>=1.9.0a0, <2.0.0",
   "opentelemetry-exporter-gcp-monitoring>=1.9.0a0, <2.0.0",
   "opentelemetry-exporter-gcp-trace>=1.9.0, <2.0.0",
   "opentelemetry-exporter-otlp-proto-http>=1.36.0",
   "opentelemetry-resourcedetector-gcp>=1.9.0a0, <2.0.0",
   "opentelemetry-sdk>=1.37.0, <=1.37.0",
-  "pydantic>=2.0, <3.0.0",                                  # For data validation/models
-  "python-dateutil>=2.9.0.post0, <3.0.0",                   # For Vertext AI Session Service
-  "python-dotenv>=1.0.0, <2.0.0",                           # To manage environment variables
+  "pydantic>=2.0, <3.0.0",                                   # For data validation/models
+  "python-dateutil>=2.9.0.post0, <3.0.0",                    # For Vertext AI Session Service
+  "python-dotenv>=1.0.0, <2.0.0",                            # To manage environment variables
   "requests>=2.32.4, <3.0.0",
-  "sqlalchemy-spanner>=1.14.0",                             # Spanner database session service
-  "sqlalchemy>=2.0, <3.0.0",                                # SQL database ORM
-  "starlette>=0.46.2, <1.0.0",                              # For FastAPI CLI
-  "tenacity>=8.0.0, <9.0.0",                                # For Retry management
+  "sqlalchemy-spanner>=1.14.0",                              # Spanner database session service
+  "sqlalchemy>=2.0, <3.0.0",                                 # SQL database ORM
+  "starlette>=0.46.2, <1.0.0",                               # For FastAPI CLI
+  "tenacity>=8.0.0, <9.0.0",                                 # For Retry management
   "typing-extensions>=4.5, <5",
-  "tzlocal>=5.3, <6.0",                                     # Time zone utilities
-  "uvicorn>=0.34.0, <1.0.0",                                # ASGI server for FastAPI
-  "watchdog>=6.0.0, <7.0.0",                                # For file change detection and hot reload
-  "websockets>=15.0.1, <16.0.0",                            # For BaseLlmFlow
+  "tzlocal>=5.3, <6.0",                                      # Time zone utilities
+  "uvicorn>=0.34.0, <1.0.0",                                 # ASGI server for FastAPI
+  "watchdog>=6.0.0, <7.0.0",                                 # For file change detection and hot reload
+  "websockets>=15.0.1, <16.0.0",                             # For BaseLlmFlow
   # go/keep-sorted end
 ]
 dynamic = ["version"]
@@ -111,13 +111,13 @@ eval = [
 test = [
   # go/keep-sorted start
   "a2a-sdk>=0.3.0,<0.4.0;python_version>='3.10'",
-  "anthropic>=0.43.0",                      # For anthropic model tests
-  "kubernetes>=29.0.0",                     # For GkeCodeExecutor
+  "anthropic>=0.43.0",                            # For anthropic model tests
+  "kubernetes>=29.0.0",                           # For GkeCodeExecutor
   "langchain-community>=0.3.17",
-  "langgraph>=0.2.60, <0.4.8",              # For LangGraphAgent
-  "litellm>=1.75.5, <2.0.0",                # For LiteLLM tests
-  "llama-index-readers-file>=0.4.0",        # For retrieval tests
-  "openai>=1.100.2",                        # For LiteLLM
+  "langgraph>=0.2.60, <0.4.8",                    # For LangGraphAgent
+  "litellm>=1.75.5, <2.0.0",                      # For LiteLLM tests
+  "llama-index-readers-file>=0.4.0",              # For retrieval tests
+  "openai>=1.100.2",                              # For LiteLLM
   "pytest>=8.3.4",
   "pytest-asyncio>=0.25.0",
   "pytest-mock>=3.14.0",
@@ -139,22 +139,20 @@ docs = [
 
 # Optional extensions
 extensions = [
-  "anthropic>=0.43.0",                         # For anthropic model support
-  "beautifulsoup4>=3.2.2",                     # For load_web_page tool.
-  "crewai[tools];python_version>='3.10'",      # For CrewaiTool
-  "docker>=7.0.0",                             # For ContainerCodeExecutor
-  "kubernetes>=29.0.0",                        # For GkeCodeExecutor
-  "langgraph>=0.2.60, <0.4.8",                 # For LangGraphAgent
-  "litellm>=1.75.5",                           # For LiteLlm class. Currently has OpenAI limitations. TODO: once LiteLlm fix it
-  "llama-index-readers-file>=0.4.0",           # For retrieval using LlamaIndex.
-  "llama-index-embeddings-google-genai>=0.3.0",# For files retrieval using LlamaIndex.
-  "lxml>=5.3.0",                               # For load_web_page tool.
-  "toolbox-core>=0.1.0",                       # For tools.toolbox_toolset.ToolboxToolset
+  "anthropic>=0.43.0",                          # For anthropic model support
+  "beautifulsoup4>=3.2.2",                      # For load_web_page tool.
+  "crewai[tools];python_version>='3.10'",       # For CrewaiTool
+  "docker>=7.0.0",                              # For ContainerCodeExecutor
+  "kubernetes>=29.0.0",                         # For GkeCodeExecutor
+  "langgraph>=0.2.60, <0.4.8",                  # For LangGraphAgent
+  "litellm>=1.75.5",                            # For LiteLlm class. Currently has OpenAI limitations. TODO: once LiteLlm fix it
+  "llama-index-readers-file>=0.4.0",            # For retrieval using LlamaIndex.
+  "llama-index-embeddings-google-genai>=0.3.0", # For files retrieval using LlamaIndex.
+  "lxml>=5.3.0",                                # For load_web_page tool.
+  "toolbox-core>=0.1.0",                        # For tools.toolbox_toolset.ToolboxToolset
 ]
 
-otel-gcp = [
-  "opentelemetry-instrumentation-google-genai>=0.3b0, <1.0.0",
-]
+otel-gcp = ["opentelemetry-instrumentation-google-genai>=0.3b0, <1.0.0"]
 
 
 [tool.pyink]

src/google/adk/agents/base_agent.py

@@ -155,8 +155,8 @@ class MyAgent(BaseAgent):
 
   Returns:
     Optional[types.Content]: The content to return to the user.
-      When the content is present, the provided content will be used as agent
-      response and appended to event history as agent response.
+      When the content is present, an additional event with the provided content
+      will be appended to event history as an additional agent response.
   """
 
   def _load_agent_state(