Merge branch 'main' into cli-pass-plugin

Author: igooch

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.

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

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

pyproject.toml

@@ -48,6 +48,7 @@ dependencies = [
   "python-dateutil>=2.9.0.post0, <3.0.0",           # For Vertext AI Session Service
   "python-dotenv>=1.0.0, <2.0.0",                   # To manage environment variables
   "requests>=2.32.4, <3.0.0",
+  "sqlalchemy-spanner>=1.14.0",                     # Spanner database session service
   "sqlalchemy>=2.0, <3.0.0",                        # SQL database ORM
   "starlette>=0.46.2, <1.0.0",                      # For FastAPI CLI
   "tenacity>=8.0.0, <9.0.0",                        # For Retry management
@@ -104,7 +105,7 @@ test = [
   "langgraph>=0.2.60, <= 0.4.10",    # For LangGraphAgent
   "litellm>=1.75.5, <2.0.0",                 # For LiteLLM tests
   "llama-index-readers-file>=0.4.0", # For retrieval tests
-  "openai<=1.99.9", # For LiteLLM
+  "openai>=1.100.2", # For LiteLLM
   "pytest-asyncio>=0.25.0",
   "pytest-mock>=3.14.0",
   "pytest-xdist>=3.6.1",

src/google/adk/agents/base_agent_config.py

@@ -24,6 +24,7 @@
 
 from pydantic import BaseModel
 from pydantic import ConfigDict
+from pydantic import Field
 
 from ..utils.feature_decorator import experimental
 from .common_configs import AgentRefConfig
@@ -43,32 +44,41 @@ class BaseAgentConfig(BaseModel):
       extra='allow',
   )
 
-  agent_class: Union[Literal['BaseAgent'], str] = 'BaseAgent'
-  """Required. The class of the agent. The value is used to differentiate
-  among different agent classes."""
+  agent_class: Union[Literal['BaseAgent'], str] = Field(
+      default='BaseAgent',
+      description=(
+          'Required. The class of the agent. The value is used to differentiate'
+          ' among different agent classes.'
+      ),
+  )
 
-  name: str
-  """Required. The name of the agent."""
+  name: str = Field(description='Required. The name of the agent.')
 
-  description: str = ''
-  """Optional. The description of the agent."""
+  description: str = Field(
+      default='', description='Optional. The description of the agent.'
+  )
 
-  sub_agents: Optional[List[AgentRefConfig]] = None
-  """Optional. The sub-agents of the agent."""
+  sub_agents: Optional[List[AgentRefConfig]] = Field(
+      default=None, description='Optional. The sub-agents of the agent.'
+  )
 
-  before_agent_callbacks: Optional[List[CodeConfig]] = None
-  """Optional. The before_agent_callbacks of the agent.
+  before_agent_callbacks: Optional[List[CodeConfig]] = Field(
+      default=None,
+      description="""\
+Optional. The before_agent_callbacks of the agent.
 
-  Example:
+Example:
 
-    ```
-    before_agent_callbacks:
-      - name: my_library.security_callbacks.before_agent_callback
-    ```
-  """
+  ```
+  before_agent_callbacks:
+    - name: my_library.security_callbacks.before_agent_callback
+  ```""",
+  )
 
-  after_agent_callbacks: Optional[List[CodeConfig]] = None
-  """Optional. The after_agent_callbacks of the agent."""
+  after_agent_callbacks: Optional[List[CodeConfig]] = Field(
+      default=None,
+      description='Optional. The after_agent_callbacks of the agent.',
+  )
 
   def to_agent_config(
       self, custom_agent_config_cls: Type[TBaseAgentConfig]