chore: import upstream snapshot with attribution

contributing/samples/integrations/gcs/README.md

@@ -0,0 +1,100 @@
+# GCS Tools Sample
+
+## Introduction
+
+This sample agent demonstrates the Google Cloud Storage (GCS) first-party tools in ADK,
+distributed via the `google.adk.integrations.gcs` module. These tools include:
+
+1. `gcs_get_bucket`
+
+Get metadata information about a GCS bucket.
+
+1. `gcs_list_objects`
+
+List object names in a GCS bucket.
+
+1. `gcs_get_object_metadata`
+
+Get metadata information about a GCS object (blob).
+
+## 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_ENTERPRISE=FALSE
+- GOOGLE_API_KEY={your api key}
+
+### With Application Default Credentials (gcloud)
+
+This is the easiest way to use your own Google Cloud identity for both the tools AND the LLM.
+
+1. Install the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install).
+1. Run `gcloud auth application-default login` in your terminal.
+1. Configure your environment to use Vertex AI (which supports ADC) instead of AI Studio:
+   - `export GOOGLE_GENAI_USE_ENTERPRISE=TRUE`
+   - `export GOOGLE_CLOUD_PROJECT={your-project-id}`
+1. Ensure the Vertex AI API is enabled and you have the correct permissions:
+   - Enable API: `gcloud services enable aiplatform.googleapis.com`
+   - Grant Role: `gcloud projects add-iam-policy-binding {your-project-id} --member="user:{your-email}" --role="roles/aiplatform.user"`
+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" and
+   "https://www.googleapis.com/auth/devstorage.full_control" as a declaration, this is used
+   for review purpose.
+
+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
+
+- Show me metadata for the my-bucket bucket.
+- List all objects in the my-bucket bucket.
+- Get metadata for the my-object.txt object in my-bucket.
+- Download the GCS object my-object.txt in my-bucket to a local file ~/Downloads/downloaded.txt.
+- Upload my local file /tmp/local_report.pdf to my-bucket as report.pdf.

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

@@ -0,0 +1,81 @@
+# 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
+
+from google.adk.agents.llm_agent import LlmAgent
+from google.adk.auth.auth_credential import AuthCredentialTypes
+from google.adk.integrations.gcs import GCSToolset
+from google.adk.integrations.gcs.gcs_credentials import GCSCredentialsConfig
+from google.adk.integrations.gcs.settings import Capabilities
+from google.adk.integrations.gcs.settings import GCSToolSettings
+import google.auth
+
+# Define an appropriate credential type.
+# Set to None to use Application Default Credentials (ADC).
+# This is the recommended way to use your `gcloud` credentials locally:
+# Run `gcloud auth application-default login` in your terminal first.
+CREDENTIALS_TYPE = None
+
+# Define GCS tool config (default is READ_ONLY; add Capabilities.READ_WRITE for modification access)
+tool_settings = GCSToolSettings(capabilities=[Capabilities.READ_WRITE])
+
+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 = GCSCredentialsConfig(
+      client_id=os.getenv("OAUTH_CLIENT_ID"),
+      client_secret=os.getenv("OAUTH_CLIENT_SECRET"),
+      scopes=[
+          "https://www.googleapis.com/auth/cloud-platform",
+          "https://www.googleapis.com/auth/devstorage.full_control",
+      ],
+  )
+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 = GCSCredentialsConfig(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 = GCSCredentialsConfig(
+      credentials=application_default_credentials
+  )
+
+gcs_toolset = GCSToolset(
+    credentials_config=credentials_config, gcs_tool_settings=tool_settings
+)
+
+# The variable name `root_agent` determines what your root agent is for the
+# debug CLI
+root_agent = LlmAgent(
+    model="gemini-2.5-flash",
+    name="gcs_agent",
+    description=(
+        "Agent to answer questions about Google Cloud Storage (GCS) buckets"
+        " and objects."
+    ),
+    instruction="""\
+        You are a storage agent with access to several GCS tools.
+        Make use of those tools to answer the user's questions about buckets and objects.
+    """,
+    tools=[
+        gcs_toolset,
+    ],
+)