Merge branch 'main' into fix-a2a-json-unboundlocal

Author: rohityan

.github/workflows/analyze-releases-for-adk-docs-updates.yml

@@ -45,15 +45,15 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
 
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
           python-version: '3.11'
 
       - name: Load adk-bot SSH Private Key
-        uses: webfactory/ssh-agent@v0.9.1
+        uses: webfactory/ssh-agent@a6f90b1f127823b31d4d4a8d96047790581349bd # v0.9.1
         with:
           ssh-private-key: ${{ secrets.ADK_BOT_SSH_PRIVATE_KEY }}
 
@@ -64,7 +64,7 @@ jobs:
 
       - name: Restore session DB from cache
         if: ${{ github.event.inputs.resume == 'true' }}
-        uses: actions/cache/restore@v4
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: contributing/samples/adk_team/adk_documentation/adk_release_analyzer/sessions.db
           key: analyzer-session-db-${{ github.run_id }}-${{ github.run_attempt }}
@@ -102,7 +102,7 @@ jobs:
 
       - name: Save session DB to cache
         if: always()
-        uses: actions/cache/save@v4
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: contributing/samples/adk_team/adk_documentation/adk_release_analyzer/sessions.db
           key: analyzer-session-db-${{ github.run_id }}-${{ github.run_attempt }}

.github/workflows/release-finalize.yml

@@ -59,7 +59,7 @@ jobs:
             echo "manifest_file=.github/.release-please-manifest.json" >> $GITHUB_OUTPUT
           fi
 
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
         if: steps.check.outputs.is_release_pr == 'true'
         with:
           ref: ${{ github.event.pull_request.base.ref }}

.github/workflows/release-update-adk-web.yaml

@@ -36,7 +36,7 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v6
+      uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
       with:
         persist-credentials: false
 
@@ -78,7 +78,7 @@ jobs:
         echo "email=$(echo "$USER_JSON" | jq -r '.id')+$(echo "$USER_JSON" | jq -r '.login')@users.noreply.github.com" >> $GITHUB_OUTPUT
 
     - name: Create Pull Request
-      uses: peter-evans/create-pull-request@v6
+      uses: peter-evans/create-pull-request@c5a7806660adbe173f04e3e038b0ccdcd758773c # v6
       with:
         token: ${{ secrets.RELEASE_PAT }}
         commit-message: "Update compiled adk web files from ${{ github.event.inputs.adk_web_repo }}@${{ github.event.inputs.adk_web_tag || 'latest' }}"

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

contributing/samples/managed_agent/system_instruction/README.md

@@ -0,0 +1,60 @@
+# Managed Agent — System Instruction
+
+> 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` whose behavior is shaped by its `instruction`
+field. `instruction` is forwarded to the Managed Agents API as the interaction's
+system instruction (the same role `LlmAgent.instruction` plays for a local
+model). Here it pins a persona and output format, so its effect is visible in
+every reply.
+
+`instruction` accepts either a plain string (which may embed `{state_var}`
+placeholders resolved from session state) or an `InstructionProvider` callable.
+This sample uses an **`InstructionProvider`**: `persona_instruction` takes a
+`ReadonlyContext`, reads the reply language from `state['response_language']`
+(defaulting to English), and returns the instruction string. Because a provider
+is invoked on every turn, the instruction is rebuilt each turn from the current
+state; unlike a string, it bypasses `{placeholder}` injection, so you build the
+final text yourself. A provider may also be `async` (return an awaitable `str`).
+
+## Sample Inputs
+
+- `What is the capital of France?`
+
+  The reply obeys the instruction: a single terse sentence ending with a
+  relevant emoji, in the language from `state['response_language']` (English by
+  default).
+
+- `And Japan?`
+
+  A follow-up turn that reuses the recovered remote sandbox and previous
+  interaction. The provider runs again on this turn, demonstrating that the
+  system instruction is resolved and sent on chained turns too — and would pick
+  up any change to `response_language` in session state.
+
+## Graph
+
+```mermaid
+graph LR
+    User -->|message| ManagedAgent
+    ManagedAgent -->|interactions.create + system_instruction| ManagedAgentsAPI
+    ManagedAgentsAPI -->|streamed events| ManagedAgent
+    ManagedAgent -->|reply shaped by the instruction| User
+```
+
+## How To
+
+- **Set the instruction**: pass `instruction=...` to `ManagedAgent`. A string is
+  sent as-is (after `{placeholder}` resolution); an `InstructionProvider`
+  callable is invoked per turn and bypasses placeholder injection.
+- **Use an `InstructionProvider`**: define a callable that takes a
+  `ReadonlyContext` and returns a `str` (or an awaitable `str`), then pass it as
+  `instruction`. Read `readonly_context.state` to build the instruction
+  dynamically — here `state['response_language']` selects the reply language.
+- **Observe the effect**: every reply follows the persona/format the instruction
+  specifies, on the first turn and on chained follow-up turns.
+- **Drive it**: a `ManagedAgent` is a `BaseAgent`, so a standard `Runner` runs it
+  just like any other agent.

contributing/samples/managed_agent/system_instruction/__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