feat(bigquery): add conversational analytics tools for Data Agents (googleapis#2517)

Implements new tools to interact with BigQuery Data Agents and aligns
BigQuery source method names with other sources for future cross-source
compatibility.

- Add three new tools: 'ask_data_agent', 'get_data_agent_info', and
'list_accessible_data_agents' under 'conversationalanalytics'.
- Rename BigQuery source methods to 'GoogleCloudProject' and
'GoogleCloudLocation' to unify interface with other source types.
- Update 'GoogleCloudTokenSourceWithScope' to support flexible scope
parameterization.
- Update existing BigQuery tools to use consistent source method names.
- Add 'bigquery-conversational-analytics-with-data-agent' prebuilt
config.
- Include comprehensive integration tests for Data Agent tools.
- Update documentation for the new prebuilt toolset.

## Description

> Should include a concise description of the changes (bug or feature),
it's
> impact, along with a summary of the solution

## PR Checklist

> Thank you for opening a Pull Request! Before submitting your PR, there
are a
> few things you can do to make sure it goes smoothly:

- [ ] Make sure you reviewed

[CONTRIBUTING.md](https://github.com/googleapis/genai-toolbox/blob/main/CONTRIBUTING.md)
- [ ] Make sure to open an issue as a

[bug/issue](https://github.com/googleapis/genai-toolbox/issues/new/choose)
  before writing your code! That way we can discuss the change, evaluate
  designs, and agree on the general idea
- [ ] Ensure the tests and linter pass
- [ ] Code coverage does not decrease (if any source code was changed)
- [ ] Appropriate docs were updated (if necessary)
- [ ] Make sure to add `!` if this involve a breaking change

🛠️ Fixes #<issue_number_goes_here>

Author: Genesis929

cmd/internal/imports.go

@@ -83,6 +83,9 @@ import (
 	_ "github.com/googleapis/genai-toolbox/internal/tools/cockroachdb/cockroachdblistschemas"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/cockroachdb/cockroachdblisttables"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/cockroachdb/cockroachdbsql"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/conversationalanalytics/conversationalanalyticsaskdataagent"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/conversationalanalytics/conversationalanalyticsgetdataagentinfo"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/conversationalanalytics/conversationalanalyticslistaccessibledataagents"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/couchbase"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/dataform/dataformcompilelocal"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/dataplex/dataplexlookupcontext"

docs/en/integrations/cloudgda/prebuilt-configs/_index.md

@@ -0,0 +1,5 @@
+---
+title: "Prebuilt Configs"
+type: docs
+description: "Prebuilt configurations for Conversational Analytics to perform natural language data analysis via Data Agents."
+---

docs/en/integrations/cloudgda/prebuilt-configs/conversational-analytics-with-data-agent.md

@@ -0,0 +1,28 @@
+---
+title: "Conversational Analytics with Data Agent"
+type: docs
+description: "Details of the Conversational Analytics with Data Agent prebuilt configuration."
+---
+
+## Conversational Analytics with Data Agent
+
+*   `--prebuilt` value: `conversational-analytics-with-data-agent`
+*   **Environment Variables:**
+    *   `CLOUD_GDA_PROJECT`: The GCP project ID.
+    *   `CLOUD_GDA_LOCATION`: (Optional) The location of the data agent (e.g., `us` or `eu`). Defaults to `global`.
+    *   `CLOUD_GDA_USE_CLIENT_OAUTH`: (Optional) If `true`, forwards the client's
+        OAuth access token for authentication. Defaults to `false`.
+    *   `CLOUD_GDA_MAX_RESULTS`: (Optional) The maximum number of rows
+        to return. Defaults to `50`.
+*   **Permissions:**
+    *   **Gemini Data Analytics Stateless Chat User (Beta)** (`roles/geminidataanalytics.dataAgentStatelessUser`) to interact with the data agent.
+    *   **BigQuery User** (`roles/bigquery.user`) and **BigQuery Data Viewer** (`roles/bigquery.dataViewer`) on the underlying datasets/tables to allow the data agent to execute queries.
+*   **Tools:**
+    *   `ask_data_agent`: Use this tool to perform natural language data analysis,
+        get insights, or answer complex questions using pre-configured data
+        sources via a specific Data Agent. For more information on
+        required roles, API setup, and IAM configuration, see the setup and
+        authentication section of the [Conversational Analytics API
+        documentation](https://cloud.google.com/gemini/docs/conversational-analytics-api/overview).
+    *   `get_data_agent_info`: Retrieve details about a specific data agent.
+    *   `list_accessible_data_agents`: List data agents that are accessible.

docs/en/integrations/cloudgda/tools/conversational-analytics-ask-data-agent.md

@@ -0,0 +1,64 @@
+---
+title: "conversational-analytics-ask-data-agent"
+type: docs
+weight: 1
+description: >
+  A "conversational-analytics-ask-data-agent" tool allows conversational interaction with a Conversational Analytics source.
+aliases:
+- /resources/tools/conversational-analytics-ask-data-agent
+---
+
+## About
+
+A `conversational-analytics-ask-data-agent` tool allows you to ask questions about
+your data in natural language.
+
+This function takes a user's question (which can include conversational history
+for context) and references to a specific BigQuery Data Agent, and sends them to a
+stateless conversational API.
+
+The API uses a GenAI agent to understand the question, generate and execute SQL
+queries and Python code, and formulate an answer. This function returns a
+detailed, sequential log of this entire process, which includes any generated
+SQL or Python code, the data retrieved, and the final text answer.
+
+**Note**: This tool requires additional setup in your project. Please refer to
+the official Conversational Analytics API
+documentation
+for instructions.
+
+It's compatible with the following sources:
+
+- cloud-gemini-data-analytics
+
+`conversational-analytics-ask-data-agent` accepts the following parameters:
+
+- **`user_query_with_context`:** The question to ask the agent, potentially 
+  including conversation history for context.
+- **`data_agent_id`:** The ID of the data agent to ask.
+
+## Example
+
+```yaml
+tools:
+  ask_data_agent:
+    kind: conversational-analytics-ask-data-agent
+    source: my-conversational-analytics-source
+    location: global
+    maxResults: 50
+    description: |
+      Perform natural language data analysis and get insights by interacting 
+      with a specific BigQuery Data Agent. This tool allows for conversational 
+      queries and provides detailed responses based on the agent's configured 
+      data sources.
+```
+
+## Reference
+
+| **field**   | **type** | **required** | **description**                                    |
+|-------------|:--------:|:------------:|----------------------------------------------------|
+| kind        |  string  |     true     | Must be "conversational-analytics-ask-data-agent". |
+| source      |  string  |     true     | Name of the source for chat.                       |
+| description |  string  |     true     | Description of the tool that is passed to the LLM. |
+| location    |  string  |    false     | The Google Cloud location (default: "global").     |
+| maxResults  |  integer |    false     | The maximum number of data rows to return in the tool's final response (default: 50). This only limits the amount of data included in the final tool return to prevent excessive token consumption, and does not affect the internal analytical process or intermediate steps. |

docs/en/integrations/cloudgda/tools/conversational-analytics-get-data-agent-info.md

@@ -0,0 +1,43 @@
+---
+title: "conversational-analytics-get-data-agent-info"
+type: docs
+weight: 1
+description: >
+  A "conversational-analytics-get-data-agent-info" tool allows retrieving information about a specific Conversational Analytics data agent.
+aliases:
+- /resources/tools/conversational-analytics-get-data-agent-info
+---
+
+## About
+
+A `conversational-analytics-get-data-agent-info` tool allows you to retrieve
+details about a specific data agent.
+
+It's compatible with the following sources:
+
+- cloud-gemini-data-analytics
+
+`conversational-analytics-get-data-agent-info` accepts the following parameters:
+
+- **`data_agent_id`:** The ID of the data agent to retrieve information for.
+
+## Example
+
+```yaml
+tools:
+  get_agent_info:
+    kind: conversational-analytics-get-data-agent-info
+    source: my-conversational-analytics-source
+    location: global
+    description: |
+      Use this tool to get details about a specific data agent.
+```
+
+## Reference
+
+| **field**   | **type** | **required** | **description**                                    |
+|-------------|:--------:|:------------:|----------------------------------------------------|
+| kind        |  string  |     true     | Must be "conversational-analytics-get-data-agent-info". |
+| source      |  string  |     true     | Name of the source.                                |
+| description |  string  |     true     | Description of the tool that is passed to the LLM. |
+| location    |  string  |    false     | The Google Cloud location (default: "global").     |

docs/en/integrations/cloudgda/tools/conversational-analytics-list-accessible-data-agents.md

@@ -0,0 +1,41 @@
+---
+title: "conversational-analytics-list-accessible-data-agents"
+type: docs
+weight: 1
+description: >
+  A "conversational-analytics-list-accessible-data-agents" tool allows listing accessible Conversational Analytics data agents.
+aliases:
+- /resources/tools/conversational-analytics-list-accessible-data-agents
+---
+
+## About
+
+A `conversational-analytics-list-accessible-data-agents` tool allows you to list
+data agents that are accessible.
+
+It's compatible with the following sources:
+
+- cloud-gemini-data-analytics
+
+`conversational-analytics-list-accessible-data-agents` does not accept any parameters.
+
+## Example
+
+```yaml
+tools:
+  list_agents:
+    kind: conversational-analytics-list-accessible-data-agents
+    source: my-conversational-analytics-source
+    location: global
+    description: |
+      Use this tool to list available data agents.
+```
+
+## Reference
+
+| **field**   | **type** | **required** | **description**                                    |
+|-------------|:--------:|:------------:|----------------------------------------------------|
+| kind        |  string  |     true     | Must be "conversational-analytics-list-accessible-data-agents". |
+| source      |  string  |     true     | Name of the source.                                |
+| description |  string  |     true     | Description of the tool that is passed to the LLM. |
+| location    |  string  |    false     | The Google Cloud location (default: "global").     |

internal/prebuiltconfigs/prebuiltconfigs_test.go

@@ -26,6 +26,7 @@ var expectedToolSources = []string{
 	"alloydb-postgres-admin",
 	"alloydb-postgres-observability",
 	"alloydb-postgres",
+	"conversational-analytics-with-data-agent",
 	"bigquery",
 	"clickhouse",
 	"cloud-healthcare",
@@ -113,6 +114,7 @@ func TestGetPrebuiltTool(t *testing.T) {
 	alloydb_observability_config := getOrFatal(t, "alloydb-postgres-observability")
 	alloydb_config := getOrFatal(t, "alloydb-postgres")
 	bigquery_config := getOrFatal(t, "bigquery")
+	conversational_analytics_config := getOrFatal(t, "conversational-analytics-with-data-agent")
 	clickhouse_config := getOrFatal(t, "clickhouse")
 	cloudsqlpg_observability_config := getOrFatal(t, "cloud-sql-postgres-observability")
 	cloudsqlpg_config := getOrFatal(t, "cloud-sql-postgres")
@@ -156,6 +158,9 @@ func TestGetPrebuiltTool(t *testing.T) {
 	if len(bigquery_config) <= 0 {
 		t.Fatalf("unexpected error: could not fetch bigquery prebuilt tools yaml")
 	}
+	if len(conversational_analytics_config) <= 0 {
+		t.Fatalf("unexpected error: could not fetch bigquery conversational analytics prebuilt tools yaml")
+	}
 	if len(clickhouse_config) <= 0 {
 		t.Fatalf("unexpected error: could not fetch clickhouse prebuilt tools yaml")
 	}

internal/prebuiltconfigs/tools/conversational-analytics-with-data-agent.yaml

@@ -0,0 +1,53 @@
+# 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.
+
+sources:
+  conversational-analytics-source:
+    kind: "cloud-gemini-data-analytics"
+    projectId: ${CLOUD_GDA_PROJECT}
+    useClientOAuth: ${CLOUD_GDA_USE_CLIENT_OAUTH:false}
+
+tools:
+  list-accessible-data-agents:
+    kind: conversational-analytics-list-accessible-data-agents
+    source: conversational-analytics-source
+    location: ${CLOUD_GDA_LOCATION:global}
+    description: |
+      List all available Data Agents that can be used for
+      conversational analytics in the current project.
+
+  get-data-agent-info:
+    kind: conversational-analytics-get-data-agent-info
+    source: conversational-analytics-source
+    location: ${CLOUD_GDA_LOCATION:global}
+    description: |
+      Retrieve detailed information about a specific Data Agent
+      using its ID.
+
+  ask-data-agent:
+    kind: conversational-analytics-ask-data-agent
+    source: conversational-analytics-source
+    location: ${CLOUD_GDA_LOCATION:global}
+    maxResults: ${CLOUD_GDA_MAX_RESULTS:50}
+    description: |
+      Perform natural language data analysis and get insights by interacting
+      with a specific Data Agent. This tool allows for conversational
+      queries and provides detailed responses based on the agent's configured
+      data sources.
+
+toolsets:
+  conversational_analytics_tools:
+    - list-accessible-data-agents
+    - get-data-agent-info
+    - ask-data-agent

internal/sources/cloudgda/cloud_gda.go

@@ -24,10 +24,12 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/util"
 	"go.opentelemetry.io/otel/trace"
 	"golang.org/x/oauth2"
+	"golang.org/x/oauth2/google"
 	"google.golang.org/api/option"
 )
 
 const SourceType string = "cloud-gemini-data-analytics"
+const CloudPlatformScope string = "https://www.googleapis.com/auth/cloud-platform"
 
 // NewDataChatClient can be overridden for testing.
 var NewDataChatClient = geminidataanalytics.NewDataChatClient
@@ -103,6 +105,18 @@ func (s *Source) GetProjectID() string {
 	return s.ProjectID
 }
 
+func (s *Source) GoogleCloudTokenSourceWithScope(ctx context.Context, scope string) (oauth2.TokenSource, error) {
+	if scope == "" {
+		scope = CloudPlatformScope
+	}
+
+	creds, err := google.FindDefaultCredentials(ctx, scope)
+	if err != nil {
+		return nil, fmt.Errorf("failed to find default credentials: %w", err)
+	}
+	return creds.TokenSource, nil
+}
+
 func (s *Source) UseClientAuthorization() bool {
 	return s.UseClientOAuth
 }