diff --git a/contributing/samples/bigtable/README.md b/contributing/samples/bigtable/README.md new file mode 100644 index 00000000..d5d42f3e --- /dev/null +++ b/contributing/samples/bigtable/README.md @@ -0,0 +1,104 @@ +# Bigtable Tools Sample + +## Introduction + +This sample agent demonstrates the Bigtable first-party tools in ADK, +distributed via the `google.adk.tools.bigtable` module. These tools include: + +1. `bigtable_list_instances` + + Fetches Bigtable instance ids in a Google Cloud project. + +1. `bigtable_get_instance_info` + + Fetches metadata information about a Bigtable instance. + +1. `bigtable_list_tables` + + Fetches table ids in a Bigtable instance. + +1. `bigtable_get_table_info` + + Fetches metadata information about a Bigtable table. + +1. `bigtable_execute_sql` + + Runs a DQL SQL query in Bigtable database. + +## 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/bigtable.admin" and + "https://www.googleapis.com/auth/bigtable.data" as 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 all instances in the my-project. +* Show me all tables in the my-instance instance in my-project. +* Describe the schema of the my-table table in the my-instance instance in my-project. +* Show me the first 10 rows of data from the my-table table in the my-instance instance in my-project. diff --git a/contributing/samples/bigtable/__init__.py b/contributing/samples/bigtable/__init__.py new file mode 100644 index 00000000..c48963cd --- /dev/null +++ b/contributing/samples/bigtable/__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 diff --git a/contributing/samples/bigtable/agent.py b/contributing/samples/bigtable/agent.py new file mode 100644 index 00000000..25e90d8d --- /dev/null +++ b/contributing/samples/bigtable/agent.py @@ -0,0 +1,76 @@ +# 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 + +from google.adk.agents.llm_agent import LlmAgent +from google.adk.auth.auth_credential import AuthCredentialTypes +from google.adk.tools.bigtable.bigtable_credentials import BigtableCredentialsConfig +from google.adk.tools.bigtable.bigtable_toolset import BigtableToolset +from google.adk.tools.bigtable.settings import BigtableToolSettings +import google.auth + +# Define an appropriate credential type +CREDENTIALS_TYPE = AuthCredentialTypes.OAUTH2 + + +# Define Bigtable tool config with read capability set to allowed. +tool_settings = BigtableToolSettings() + +if CREDENTIALS_TYPE == AuthCredentialTypes.OAUTH2: + # Initiaze the tools to do interactive OAuth + # The environment variables OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET + # must be set + credentials_config = BigtableCredentialsConfig( + client_id=os.getenv("OAUTH_CLIENT_ID"), + client_secret=os.getenv("OAUTH_CLIENT_SECRET"), + scopes=[ + "https://www.googleapis.com/auth/bigtable.admin", + "https://www.googleapis.com/auth/bigtable.data", + ], + ) +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 = BigtableCredentialsConfig(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 = BigtableCredentialsConfig( + credentials=application_default_credentials + ) + +bigtable_toolset = BigtableToolset( + credentials_config=credentials_config, bigtable_tool_settings=tool_settings +) + +# The variable name `root_agent` determines what your root agent is for the +# debug CLI +root_agent = LlmAgent( + model="gemini-1.5-flash", + name="bigtable_agent", + description=( + "Agent to answer questions about Bigtable database tables and" + " execute SQL queries." + ), # TODO(b/360128447): Update description + instruction="""\ + You are a data agent with access to several Bigtable tools. + Make use of those tools to answer the user's questions. + """, + tools=[bigtable_toolset], +)