Merge branch 'main' into fix/skill-toolset-instruction-tool-filter

Author: rohityan

contributing/samples/integrations/eventarc/README.md

@@ -0,0 +1,115 @@
+# Eventarc Tools Sample
+
+## Introduction
+
+This sample agent demonstrates the Eventarc first-party tool in ADK,
+distributed via the `google.adk.integrations.eventarc` module. This tool suite currently includes:
+
+1. `publish_message`
+
+Publishes a structured event in CloudEvents format to a Google Cloud Eventarc message bus.
+
+## How to use
+
+Set up environment variables in your `.env` file for using
+[Google AI Studio](https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-ai-studio)
+or
+[Google Cloud Vertex AI](https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai)
+for the LLM service for your agent. For example, for using Google AI Studio you
+would set:
+
+- GOOGLE_GENAI_USE_VERTEXAI=FALSE
+- GOOGLE_API_KEY={your api key}
+
+### With Application Default Credentials
+
+This mode is useful for quick development when the agent builder is the only
+user interacting with the agent. The tools are run with these credentials.
+
+1. Create application default credentials on the machine where the agent would
+   be running by following https://cloud.google.com/docs/authentication/provide-credentials-adc.
+
+1. Set `CREDENTIALS_TYPE=None` in `agent.py`
+
+1. Run the agent
+
+### With Service Account Keys
+
+This mode is useful for quick development when the agent builder wants to run
+the agent with service account credentials. The tools are run with these
+credentials.
+
+1. Create service account key by following https://cloud.google.com/iam/docs/service-account-creds#user-managed-keys.
+
+1. Set `CREDENTIALS_TYPE=AuthCredentialTypes.SERVICE_ACCOUNT` in `agent.py`
+
+1. Download the key file and replace `"service_account_key.json"` with the path
+
+1. Run the agent
+
+### With Interactive OAuth
+
+1. Follow
+   https://developers.google.com/identity/protocols/oauth2#1.-obtain-oauth-2.0-credentials-from-the-dynamic_data.setvar.console_name.
+   to get your client id and client secret. Be sure to choose "web" as your client
+   type.
+
+1. Follow https://developers.google.com/workspace/guides/configure-oauth-consent to add scope "https://www.googleapis.com/auth/cloud-platform".
+
+1. Follow https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred to add http://localhost/dev-ui/ to "Authorized redirect URIs".
+
+Note: localhost here is just a hostname that you use to access the dev ui,
+replace it with the actual hostname you use to access the dev ui.
+
+1. For 1st run, allow popup for localhost in Chrome.
+
+1. Configure your `.env` file to add two more variables before running the agent:
+
+- OAUTH_CLIENT_ID={your client id}
+- OAUTH_CLIENT_SECRET={your client secret}
+
+Note: don't create a separate .env, instead put it to the same .env file that
+stores your Vertex AI or Dev ML credentials
+
+1. Set `CREDENTIALS_TYPE=AuthCredentialTypes.OAUTH2` in `agent.py` and run the agent
+
+### With Agent Identity (in Agent Runtime / Vertex AI Reasoning Engine)
+
+When deploying this agent to Agent Runtime, it can use its unique SPIFFE-based Agent Identity to authenticate. This is the recommended security best practice.
+
+1. **Configure Deployment**: Create a `.agent_engine_config.json` file in this directory to specify the identity type:
+
+   ```json
+   {
+     "identity_type": "AGENT_IDENTITY"
+   }
+   ```
+
+1. **Use Default Credentials**: Leave `CREDENTIALS_TYPE = None` in `agent.py` (which is the default). This configures the agent to use Application Default Credentials (ADC), which automatically resolves to the Agent Identity in the container runtime environment.
+
+1. **Deploy the Agent**: Deploy your agent using the ADK CLI:
+
+   ```bash
+   uv run adk deploy agent_engine \
+     --project=YOUR_PROJECT_ID \
+     --region=YOUR_REGION \
+     --display_name=eventarc-agent-test \
+     contributing/samples/integrations/eventarc
+   ```
+
+   Take note of the generated **Reasoning Engine ID** (e.g., `1234567890`) and the **Project Number** of your project.
+
+1. **Grant IAM Permissions**: Grant the Eventarc Message Bus User role (`roles/eventarc.messageBusUser`) to the Agent Identity principal at the project level:
+
+   ```bash
+   gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
+     --member="principal://agents.global.org-171145599760.system.id.goog/resources/aiplatform/projects/YOUR_PROJECT_NUMBER/locations/YOUR_REGION/reasoningEngines/YOUR_REASONING_ENGINE_ID" \
+     --role="roles/eventarc.messageBusUser"
+   ```
+
+   *Note: Eventarc Advanced message buses require `roles/eventarc.messageBusUser` for publishing, rather than `roles/eventarc.publisher`.*
+
+## Sample prompts
+
+- "Publish an event of type 'com.example.hello' to bus 'projects/my-project/locations/global/messageBuses/my-bus' with data 'Hello World' and source '//my/agent'"
+- "Send a JSON payload to Eventarc bus 'projects/my-project/locations/global/messageBuses/my-bus' representing a user sign-up event"

contributing/samples/integrations/eventarc/__init__.py

@@ -0,0 +1,13 @@
+# 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.

contributing/samples/integrations/eventarc/agent.py

@@ -0,0 +1,78 @@
+# 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.
+
+import os
+import textwrap
+
+from google.adk.agents.llm_agent import LlmAgent
+from google.adk.auth.auth_credential import AuthCredentialTypes
+from google.adk.integrations.eventarc import EventarcCredentialsConfig
+from google.adk.integrations.eventarc import EventarcToolConfig
+from google.adk.integrations.eventarc import EventarcToolset
+import google.auth
+
+# Define the desired credential type.
+# By default use Application Default Credentials (ADC) from the local
+# environment, which can be set up by following
+# https://cloud.google.com/docs/authentication/provide-credentials-adc.
+CREDENTIALS_TYPE = None
+
+# Define an appropriate application name
+EVENTARC_AGENT_NAME = "adk_sample_eventarc_agent"
+
+
+# Define Eventarc tool config.
+# You can optionally set the project_id here, or let the agent infer it from context/user input.
+tool_config = EventarcToolConfig(project_id=os.getenv("GOOGLE_CLOUD_PROJECT"))
+
+if CREDENTIALS_TYPE == AuthCredentialTypes.OAUTH2:
+  # Initialize the tools to do interactive OAuth
+  # The environment variables OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET
+  # must be set
+  credentials_config = EventarcCredentialsConfig(
+      client_id=os.getenv("OAUTH_CLIENT_ID"),
+      client_secret=os.getenv("OAUTH_CLIENT_SECRET"),
+  )
+elif CREDENTIALS_TYPE == AuthCredentialTypes.SERVICE_ACCOUNT:
+  # Initialize the tools to use the credentials in the service account key.
+  # If this flow is enabled, make sure to replace the file path with your own
+  # service account key file
+  # https://cloud.google.com/iam/docs/service-account-creds#user-managed-keys
+  creds, _ = google.auth.load_credentials_from_file("service_account_key.json")
+  credentials_config = EventarcCredentialsConfig(credentials=creds)
+else:
+  # Initialize the tools to use the application default credentials.
+  # https://cloud.google.com/docs/authentication/provide-credentials-adc
+  application_default_credentials, _ = google.auth.default()
+  credentials_config = EventarcCredentialsConfig(
+      credentials=application_default_credentials
+  )
+
+eventarc_toolset = EventarcToolset(
+    credentials_config=credentials_config, tool_config=tool_config
+)
+
+# The variable name `root_agent` determines what your root agent is for the
+# debug CLI
+root_agent = LlmAgent(
+    name=EVENTARC_AGENT_NAME,
+    description=(
+        "Agent to publish structured CloudEvents to Google Cloud Eventarc."
+    ),
+    instruction=textwrap.dedent("""\
+        You are a cloud engineer agent with access to Google Cloud Eventarc tools.
+        You can publish CloudEvents structured messages to Eventarc message buses.
+    """),
+    tools=[eventarc_toolset],
+)

src/google/adk/a2a/converters/event_converter.py

@@ -234,7 +234,13 @@ def convert_a2a_task_to_event(
     ):
       message = a2a_task.status.message
     elif a2a_task.history:
-      message = a2a_task.history[-1]
+      # Only pick agent-role messages from history; a trailing user
+      # message should not be misattributed as agent output.
+      agent_messages = [
+          m for m in a2a_task.history if m.role == _compat.ROLE_AGENT
+      ]
+      if agent_messages:
+        message = agent_messages[-1]
 
     # Convert message if available
     if message:
@@ -288,6 +294,8 @@ def convert_a2a_message_to_event(
   if a2a_message is None:
     raise ValueError("A2A message cannot be None")
 
+  genai_role = _compat.role_to_str(a2a_message.role)
+
   if not a2a_message.parts:
     logger.warning(
         "A2A message has no parts, creating event with empty content"
@@ -300,7 +308,7 @@ def convert_a2a_message_to_event(
         ),
         author=author or "a2a agent",
         branch=invocation_context.branch if invocation_context else None,
-        content=genai_types.Content(role="model", parts=[]),
+        content=genai_types.Content(role=genai_role, parts=[]),
     )
 
   try:
@@ -355,7 +363,7 @@ def convert_a2a_message_to_event(
         if long_running_tool_ids
         else None,
         content=genai_types.Content(
-            role="model",
+            role=genai_role,
             parts=output_parts,
         ),
     )

src/google/adk/agents/remote_a2a_agent.py

@@ -543,21 +543,26 @@ async def _handle_a2a_response(
             for part in event.content.parts:
               part.thought = True
           _add_mock_function_call(event, update.status.state)
-        elif isinstance(update, A2ATaskArtifactUpdateEvent) and (
-            not update.append or update.last_chunk
-        ):
+        elif isinstance(update, A2ATaskArtifactUpdateEvent):
           # This is a streaming task artifact update.
-          # We only handle full artifact updates and ignore partial updates.
-          # Note: Depends on the server implementation, there is no clear
-          # definition of what a partial update is currently. We use the two
-          # signals:
-          # 1. append: True for partial updates, False for full updates.
-          # 2. last_chunk: True for full updates, False for partial updates.
-          event = convert_a2a_task_to_event(
-              task, self.name, ctx, self._a2a_part_converter
+          # Convert only the parts carried by this update. Converting the
+          # accumulated task here would re-emit earlier chunks of the same
+          # artifact, duplicating already-streamed content.
+          if not update.artifact.parts:
+            return None
+          event = convert_a2a_message_to_event(
+              _compat.make_message(
+                  message_id="",
+                  role="agent",
+                  parts=update.artifact.parts,
+              ),
+              self.name,
+              ctx,
+              self._a2a_part_converter,
           )
           if not event:
             return None
+          event.partial = not update.last_chunk
         else:
           # This is a streaming update without a message (e.g. status change)
           # or a partial artifact update. We don't emit an event for these

src/google/adk/features/_feature_registry.py

@@ -41,6 +41,8 @@ class FeatureName(str, Enum):
   DAYTONA_ENVIRONMENT = "DAYTONA_ENVIRONMENT"
   E2B_ENVIRONMENT = "E2B_ENVIRONMENT"
   ENVIRONMENT_SIMULATION = "ENVIRONMENT_SIMULATION"
+  EVENTARC_TOOL_CONFIG = "EVENTARC_TOOL_CONFIG"
+  EVENTARC_TOOLSET = "EVENTARC_TOOLSET"
   GCS_ADMIN_TOOLSET = "GCS_ADMIN_TOOLSET"
   GCS_TOOL_SETTINGS = "GCS_TOOL_SETTINGS"
   GCS_TOOLSET = "GCS_TOOLSET"
@@ -144,6 +146,12 @@ class FeatureConfig:
     FeatureName.ENVIRONMENT_SIMULATION: FeatureConfig(
         FeatureStage.EXPERIMENTAL, default_on=True
     ),
+    FeatureName.EVENTARC_TOOL_CONFIG: FeatureConfig(
+        FeatureStage.EXPERIMENTAL, default_on=True
+    ),
+    FeatureName.EVENTARC_TOOLSET: FeatureConfig(
+        FeatureStage.EXPERIMENTAL, default_on=True
+    ),
     FeatureName.GCS_ADMIN_TOOLSET: FeatureConfig(
         FeatureStage.EXPERIMENTAL, default_on=True
     ),

src/google/adk/flows/llm_flows/agent_transfer.py

@@ -17,8 +17,8 @@
 from __future__ import annotations
 
 import typing
-from typing import Any
 from typing import AsyncGenerator
+from typing import Sequence
 
 from typing_extensions import override
 
@@ -30,8 +30,8 @@
 from ._base_llm_processor import BaseLlmRequestProcessor
 
 if typing.TYPE_CHECKING:
-  from ...agents import BaseAgent
-  from ...agents import LlmAgent
+  from ...agents.base_agent import BaseAgent
+  from ...agents.llm_agent import LlmAgent
 
 
 class _AgentTransferLlmRequestProcessor(BaseLlmRequestProcessor):
@@ -72,8 +72,12 @@ async def run_async(
 request_processor = _AgentTransferLlmRequestProcessor()
 
 
-def _build_target_agents_info(target_agent: Any) -> str:
-  # TODO: Refactor the annotation of the parameters
+class _AgentLike(typing.Protocol):
+  name: str
+  description: str
+
+
+def _build_target_agents_info(target_agent: _AgentLike) -> str:
   return f"""
 Agent name: {target_agent.name}
 Agent description: {target_agent.description}
@@ -85,17 +89,16 @@ def _build_target_agents_info(target_agent: Any) -> str:
 
 def _build_transfer_instruction_body(
     tool_name: str,
-    target_agents: list[Any],
+    target_agents: Sequence[_AgentLike],
 ) -> str:
   """Build the core transfer instruction text.
-  TODO: Refactor the annotation of the parameters
 
   This is the agent-tree-agnostic portion of transfer instructions. It
-  works with any objects having ``.name`` and ``.description`` attributes
+  works with any BaseAgent implementation.
 
   Args:
     tool_name: The name of the transfer tool (e.g. 'transfer_to_agent').
-    target_agents: Objects with ``.name`` and ``.description``.
+    target_agents: Agents available as transfer targets.
 
   Returns:
     Instruction text for the LLM about agent transfers.
@@ -128,8 +131,8 @@ def _build_transfer_instruction_body(
 
 def _build_transfer_instructions(
     tool_name: str,
-    agent: 'LlmAgent',
-    target_agents: list['BaseAgent'],
+    agent: LlmAgent,
+    target_agents: Sequence[BaseAgent],
 ) -> str:
   """Build instructions for agent transfer (agent-tree variant).