Merge branch 'main' into fix/handle-circular-refs

Author: foivos-all

.github/workflows/python-unit-tests.yml

@@ -43,7 +43,7 @@ jobs:
       run: |
         uv venv .venv
         source .venv/bin/activate
-        uv sync --extra test --extra eval --extra a2a
+        uv sync --extra test
 
     - name: Run unit tests with pytest
       run: |

contributing/samples/agent_registry_agent/README.md

@@ -0,0 +1,49 @@
+# Agent Registry Sample
+
+This sample demonstrates how to use the `AgentRegistry` client to discover agents and MCP servers registered in Google Cloud.
+
+## Setup
+
+1.  Ensure you have Google Cloud credentials configured (e.g., `gcloud auth application-default login`).
+2.  Set the following environment variables:
+
+```bash
+export GOOGLE_CLOUD_PROJECT=your-project-id
+export GOOGLE_CLOUD_LOCATION=global  # or your specific region
+```
+
+3.  Obtain the full resource names for the agents and MCP servers you want to use. You can do this by running the sample script once to list them:
+
+    ```bash
+    python3 agent.py
+    ```
+
+    Alternatively, use `gcloud` to list them:
+
+    ```bash
+    # For agents
+    gcloud alpha agent-registry agents list --project=$GOOGLE_CLOUD_PROJECT --location=$GOOGLE_CLOUD_LOCATION
+
+    # For MCP servers
+    gcloud alpha agent-registry mcp-servers list --project=$GOOGLE_CLOUD_PROJECT --location=$GOOGLE_CLOUD_LOCATION
+    ```
+
+4.  Replace `AGENT_NAME` and `MCP_SERVER_NAME` in `agent.py` with the last part of the resource names (e.g., if the name is `projects/.../agents/my-agent`, use `my-agent`).
+
+## Running the Sample
+
+Run the sample script to list available agents and MCP servers:
+
+```bash
+python3 agent.py
+```
+
+## How it Works
+
+The sample uses `AgentRegistry` to:
+- List registered agents using `list_agents()`.
+- List registered MCP servers using `list_mcp_servers()`.
+
+It also shows (in comments) how to:
+- Get a `RemoteA2aAgent` instance using `get_remote_a2a_agent(name)`.
+- Get an `McpToolset` instance using `get_mcp_toolset(name)`.

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

@@ -0,0 +1,63 @@
+# 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.
+
+"""Sample agent demonstrating Agent Registry discovery."""
+
+import os
+
+from google.adk.agents.llm_agent import LlmAgent
+from google.adk.integrations.agent_registry import AgentRegistry
+
+# Project and location can be set via environment variables:
+# GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION
+project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
+location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")
+
+# Initialize Agent Registry client
+registry = AgentRegistry(project_id=project_id, location=location)
+
+print(f"Listing agents in {project_id}/{location}...")
+agents = registry.list_agents()
+for agent in agents.get("agents", []):
+  print(f"- Agent: {agent.get('displayName')} ({agent.get('name')})")
+
+print(f"\nListing MCP servers in {project_id}/{location}...")
+mcp_servers = registry.list_mcp_servers()
+for server in mcp_servers.get("mcpServers", []):
+  print(f"- MCP Server: {server.get('displayName')} ({server.get('name')})")
+
+# Example of using a specific agent or MCP server from the registry:
+# (Note: These names should be full resource names as returned by list methods)
+
+# 1. Using a Remote A2A Agent as a sub-agent
+# TODO: Replace AGENT_NAME with your agent name
+remote_agent = registry.get_remote_a2a_agent(
+    f"projects/{project_id}/locations/{location}/agents/AGENT_NAME"
+)
+
+# 2. Using an MCP Server in a toolset
+# TODO: Replace MCP_SERVER_NAME with your MCP server name
+mcp_toolset = registry.get_mcp_toolset(
+    f"projects/{project_id}/locations/{location}/mcpServers/MCP_SERVER_NAME"
+)
+
+root_agent = LlmAgent(
+    model="gemini-2.5-flash",
+    name="discovery_agent",
+    instruction=(
+        "You have access to tools and sub-agents discovered via Registry."
+    ),
+    tools=[mcp_toolset],
+    sub_agents=[remote_agent],
+)

contributing/samples/bigquery/README.md

@@ -55,9 +55,6 @@ distributed via the `google.adk.tools.bigquery` module. These tools include:
   `ARIMA_PLUS` model and then querying it with
   `ML.DETECT_ANOMALIES` to detect time series data anomalies.
 
-11. `search_catalog`
-  Searches for data entries across projects using the Dataplex Catalog. This allows discovery of datasets, tables, and other assets.
-
 ## How to use
 
 Set up environment variables in your `.env` file for using
@@ -162,4 +159,3 @@ the necessary access tokens to call BigQuery APIs on their behalf.
 * which tables exist in the ml_datasets dataset?
 * show more details about the penguins table
 * compute penguins population per island.
-* are there any tables related to animals in project <your_project_id>?

contributing/samples/skills_agent/agent.py

@@ -19,7 +19,7 @@
 from google.adk import Agent
 from google.adk.skills import load_skill_from_dir
 from google.adk.skills import models
-from google.adk.tools import skill_toolset
+from google.adk.tools.skill_toolset import SkillToolset
 
 greeting_skill = models.Skill(
     frontmatter=models.Frontmatter(
@@ -44,15 +44,12 @@
     pathlib.Path(__file__).parent / "skills" / "weather_skill"
 )
 
-my_skill_toolset = skill_toolset.SkillToolset(
-    skills=[greeting_skill, weather_skill]
-)
+my_skill_toolset = SkillToolset(skills=[greeting_skill, weather_skill])
 
 root_agent = Agent(
     model="gemini-2.5-flash",
     name="skill_user_agent",
     description="An agent that can use specialized skills.",
-    instruction=skill_toolset.DEFAULT_SKILL_SYSTEM_INSTRUCTION,
     tools=[
         my_skill_toolset,
     ],

pyproject.toml

@@ -37,7 +37,6 @@ dependencies = [
   "google-cloud-bigquery-storage>=2.0.0",
   "google-cloud-bigquery>=2.2.0",
   "google-cloud-bigtable>=2.32.0",                           # For Bigtable database
-  "google-cloud-dataplex>=1.7.0,<3.0.0",                    # For Dataplex Catalog Search tool
   "google-cloud-discoveryengine>=0.13.12, <0.14.0",          # For Discovery Engine Search Tool
   "google-cloud-pubsub>=2.0.0, <3.0.0",                      # For Pub/Sub Tool
   "google-cloud-secret-manager>=2.22.0, <3.0.0",             # Fetching secrets in RestAPI Tool
@@ -49,13 +48,13 @@ dependencies = [
   "httpx>=0.27.0, <1.0.0",                                   # HTTP client library
   "jsonschema>=4.23.0, <5.0.0",                              # Agent Builder config validation
   "mcp>=1.23.0, <2.0.0",                                     # For MCP Toolset
-  "opentelemetry-api>=1.36.0, <1.40.0",                      # OpenTelemetry - keep below 1.40.0 to reduce risk of breaking changes around log-signal APIs.
+  "opentelemetry-api>=1.36.0, <1.39.0",                      # OpenTelemetry - keep below 1.39.0 due to current agent_engines exporter constraints.
   "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.36.0, <1.40.0",
+  "opentelemetry-sdk>=1.36.0, <1.39.0",
   "pyarrow>=14.0.0",
   "pydantic>=2.7.0, <3.0.0",                                 # For data validation/models
   "python-dateutil>=2.9.0.post0, <3.0.0",                    # For Vertext AI Session Service
@@ -125,7 +124,7 @@ test = [
   "kubernetes>=29.0.0",                           # For GkeCodeExecutor
   "langchain-community>=0.3.17",
   "langgraph>=0.2.60, <0.4.8",                    # For LangGraphAgent
-  "litellm>=1.75.5, <1.80.17",                    # For LiteLLM tests
+  "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
   "opentelemetry-instrumentation-google-genai>=0.3b0, <1.0.0",
@@ -157,7 +156,7 @@ extensions = [
   "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, <1.80.17",                  # For LiteLlm class. Currently has OpenAI limitations. TODO: once LiteLlm fix it
+  "litellm>=1.75.5, <2.0.0",                    # 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.

src/google/adk/agents/agent_config.py

@@ -16,14 +16,14 @@
 
 from typing import Annotated
 from typing import Any
-from typing import get_args
 from typing import Union
 
 from pydantic import Discriminator
 from pydantic import RootModel
 from pydantic import Tag
 
-from ..utils.feature_decorator import experimental
+from ..features import experimental
+from ..features import FeatureName
 from .base_agent_config import BaseAgentConfig
 from .llm_agent_config import LlmAgentConfig
 from .loop_agent_config import LoopAgentConfig
@@ -68,6 +68,6 @@ def agent_config_discriminator(v: Any) -> str:
 
 # Use a RootModel to represent the agent directly at the top level.
 # The `discriminator` is applied to the union within the RootModel.
-@experimental
+@experimental(FeatureName.AGENT_CONFIG)
 class AgentConfig(RootModel[ConfigsUnion]):
   """The config for the YAML schema to create an agent."""

src/google/adk/agents/base_agent.py

@@ -40,10 +40,11 @@
 
 from ..events.event import Event
 from ..events.event_actions import EventActions
+from ..features import experimental
+from ..features import FeatureName
 from ..telemetry import tracing
 from ..telemetry.tracing import tracer
 from ..utils.context_utils import Aclosing
-from ..utils.feature_decorator import experimental
 from .base_agent_config import BaseAgentConfig
 from .callback_context import CallbackContext
 
@@ -70,7 +71,7 @@
 SelfAgent = TypeVar('SelfAgent', bound='BaseAgent')
 
 
-@experimental
+@experimental(FeatureName.AGENT_STATE)
 class BaseAgentState(BaseModel):
   """Base class for all agent states."""
 
@@ -618,7 +619,7 @@ def __set_parent_agent_for_sub_agents(self) -> BaseAgent:
 
   @final
   @classmethod
-  @experimental
+  @experimental(FeatureName.AGENT_CONFIG)
   def from_config(
       cls: Type[SelfAgent],
       config: BaseAgentConfig,
@@ -642,7 +643,7 @@ def from_config(
     return cls(**kwargs)
 
   @classmethod
-  @experimental
+  @experimental(FeatureName.AGENT_CONFIG)
   def _parse_config(
       cls: Type[SelfAgent],
       config: BaseAgentConfig,

src/google/adk/agents/base_agent_config.py

@@ -26,14 +26,15 @@
 from pydantic import ConfigDict
 from pydantic import Field
 
-from ..utils.feature_decorator import experimental
+from ..features import experimental
+from ..features import FeatureName
 from .common_configs import AgentRefConfig
 from .common_configs import CodeConfig
 
 TBaseAgentConfig = TypeVar('TBaseAgentConfig', bound='BaseAgentConfig')
 
 
-@experimental
+@experimental(FeatureName.AGENT_CONFIG)
 class BaseAgentConfig(BaseModel):
   """The config for the YAML schema of a BaseAgent.