feat: Add a handwritten tool for Cloud Pub/Sub

Merge #3865

COPYBARA_INTEGRATE_REVIEW=#3865 from kamalaboulhosn:main 37a38a4
PiperOrigin-RevId: 845345128

Author: kamalaboulhosn

contributing/samples/pubsub/README.md

@@ -0,0 +1,88 @@
+# Pub/Sub Tools Sample
+
+## Introduction
+
+This sample agent demonstrates the Pub/Sub first-party tools in ADK,
+distributed via the `google.adk.tools.pubsub` module. These tools include:
+
+1. `publish_message`
+
+  Publishes a message to a Pub/Sub topic.
+
+2. `pull_messages`
+
+  Pulls messages from a Pub/Sub subscription.
+
+3. `acknowledge_messages`
+
+  Acknowledges messages on a Pub/Sub subscription.
+
+## 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/pubsub".
+
+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
+
+## Sample prompts
+
+* publish 'Hello World' to 'my-topic'
+* pull messages from 'my-subscription'
+* acknowledge message 'ack-id' from 'my-subscription'

contributing/samples/pubsub/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2025 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/pubsub/agent.py

@@ -0,0 +1,80 @@
+# Copyright 2025 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.tools.pubsub.config import PubSubToolConfig
+from google.adk.tools.pubsub.pubsub_credentials import PubSubCredentialsConfig
+from google.adk.tools.pubsub.pubsub_toolset import PubSubToolset
+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
+PUBSUB_AGENT_NAME = "adk_sample_pubsub_agent"
+
+
+# Define Pub/Sub tool config.
+# You can optionally set the project_id here, or let the agent infer it from context/user input.
+tool_config = PubSubToolConfig(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 = PubSubCredentialsConfig(
+      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 = PubSubCredentialsConfig(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 = PubSubCredentialsConfig(
+      credentials=application_default_credentials
+  )
+
+pubsub_toolset = PubSubToolset(
+    credentials_config=credentials_config, pubsub_tool_config=tool_config
+)
+
+# The variable name `root_agent` determines what your root agent is for the
+# debug CLI
+root_agent = LlmAgent(
+    model="gemini-2.5-flash",
+    name=PUBSUB_AGENT_NAME,
+    description=(
+        "Agent to publish, pull, and acknowledge messages from Google Cloud"
+        " Pub/Sub."
+    ),
+    instruction=textwrap.dedent("""\
+        You are a cloud engineer agent with access to Google Cloud Pub/Sub tools.
+        You can publish messages to topics, pull messages from subscriptions, and acknowledge messages.
+    """),
+    tools=[pubsub_toolset],
+)

pyproject.toml

@@ -37,6 +37,7 @@ dependencies = [
   "google-cloud-bigquery>=2.2.0",
   "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-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
   "google-cloud-spanner>=3.56.0, <4.0.0",                    # For Spanner database
   "google-cloud-speech>=2.30.0, <3.0.0",                     # For Audio Transcription

src/google/adk/features/_feature_registry.py

@@ -32,6 +32,7 @@ class FeatureName(str, Enum):
   GOOGLE_TOOL = "GOOGLE_TOOL"
   JSON_SCHEMA_FOR_FUNC_DECL = "JSON_SCHEMA_FOR_FUNC_DECL"
   PROGRESSIVE_SSE_STREAMING = "PROGRESSIVE_SSE_STREAMING"
+  PUBSUB_TOOLSET = "PUBSUB_TOOLSET"
   SPANNER_TOOLSET = "SPANNER_TOOLSET"
   SPANNER_TOOL_SETTINGS = "SPANNER_TOOL_SETTINGS"
 
@@ -90,6 +91,9 @@ class FeatureConfig:
     FeatureName.PROGRESSIVE_SSE_STREAMING: FeatureConfig(
         FeatureStage.WIP, default_on=False
     ),
+    FeatureName.PUBSUB_TOOLSET: FeatureConfig(
+        FeatureStage.EXPERIMENTAL, default_on=True
+    ),
     FeatureName.SPANNER_TOOLSET: FeatureConfig(
         FeatureStage.EXPERIMENTAL, default_on=True
     ),

src/google/adk/tools/pubsub/__init__.py

@@ -0,0 +1,30 @@
+# Copyright 2025 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.
+
+"""Pub/Sub Tools (Experimental).
+
+Pub/Sub Tools under this module are hand crafted and customized while the tools
+under google.adk.tools.google_api_tool are auto generated based on API
+definition. The rationales to have customized tool are:
+
+1. Better handling of base64 encoding for published messages.
+2. A richer subscribe-side API that reflects how users may want to pull/ack
+   messages.
+"""
+
+from .config import PubSubToolConfig
+from .pubsub_credentials import PubSubCredentialsConfig
+from .pubsub_toolset import PubSubToolset
+
+__all__ = ["PubSubCredentialsConfig", "PubSubToolConfig", "PubSubToolset"]