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

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/dataplexlookupentry"

docs/en/reference/prebuilt-tools.md

@@ -167,6 +167,8 @@ See [Usage Examples](../reference/cli.md#examples).
         OAuth access token for authentication. Defaults to `false`.
     *   `BIGQUERY_SCOPES`: (Optional) A comma-separated list of OAuth scopes to
         use for authentication.
+    *   `BIGQUERY_MAX_QUERY_RESULT_ROWS`: (Optional) The maximum number of rows
+        to return. Defaults to `50`.
 *   **Permissions:**
     *   **BigQuery User** (`roles/bigquery.user`) to execute queries and view
         metadata.
@@ -193,6 +195,25 @@ See [Usage Examples](../reference/cli.md#examples).
     *   `list_table_ids`: Lists tables.
     *   `search_catalog`: Search for entries based on the provided query.
 
+## BigQuery Conversational Analytics with Data Agent
+
+*   `--prebuilt` value: `bigquery-conversational-analytics-with-data-agent`
+*   **Environment Variables:**
+    *   `BIGQUERY_PROJECT`: The GCP project ID.
+    *   `BIGQUERY_USE_CLIENT_OAUTH`: (Optional) If `true`, forwards the client's
+        OAuth access token for authentication. Defaults to `false`.
+*   **Permissions:**
+    *   **Gemini Data Analytics Stateless Chat User (Beta)** (`roles/geminidataanalytics.dataAgentStatelessUser`)
+*   **Tools:**
+    *   `ask_data_agent`: Use this tool to perform data analysis, get
+        insights, or answer complex questions about the contents of specific
+        BigQuery tables. 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.
+
 ## ClickHouse
 
 *   `--prebuilt` value: `clickhouse`

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

@@ -0,0 +1,52 @@
+# 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:
+  bigquery-source:
+    kind: "bigquery"
+    project: ${BIGQUERY_PROJECT}
+    location: ${BIGQUERY_LOCATION:}
+    useClientOAuth: ${BIGQUERY_USE_CLIENT_OAUTH:false}
+    scopes: ${BIGQUERY_SCOPES:}
+    maxQueryResultRows: ${BIGQUERY_MAX_QUERY_RESULT_ROWS:50}
+
+tools:
+  list-accessible-data-agents:
+    kind: conversational-analytics-list-accessible-data-agents
+    source: bigquery-source
+    description: |
+      List all available BigQuery 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: bigquery-source
+    description: |
+      Retrieve detailed information about a specific BigQuery Data Agent
+      using its ID.
+
+  ask-data-agent:
+    kind: conversational-analytics-ask-data-agent
+    source: bigquery-source
+    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.
+
+toolsets:
+  conversational_analytics_tools:
+    - list-accessible-data-agents
+    - get-data-agent-info
+    - ask-data-agent

internal/sources/bigquery/bigquery.go

@@ -420,20 +420,23 @@ func (s *Source) UseClientAuthorization() bool {
 	return s.UseClientOAuth
 }
 
-func (s *Source) BigQueryProject() string {
+func (s *Source) GoogleCloudProject() string {
 	return s.Project
 }
 
-func (s *Source) BigQueryLocation() string {
+func (s *Source) GoogleCloudLocation() string {
 	return s.Location
 }
 
 func (s *Source) BigQueryTokenSource() oauth2.TokenSource {
 	return s.TokenSource
 }
 
-func (s *Source) BigQueryTokenSourceWithScope(ctx context.Context, scopes []string) (oauth2.TokenSource, error) {
-	if len(scopes) == 0 {
+func (s *Source) GoogleCloudTokenSourceWithScope(ctx context.Context, scope string) (oauth2.TokenSource, error) {
+	var scopes []string
+	if scope != "" {
+		scopes = []string{scope}
+	} else {
 		scopes = s.Scopes
 		if len(scopes) == 0 {
 			scopes = []string{CloudPlatformScope}

internal/tools/bigquery/bigqueryconversationalanalytics/bigqueryconversationalanalytics.go

@@ -58,9 +58,9 @@ func newConfig(ctx context.Context, name string, decoder *yaml.Decoder) (tools.T
 
 type compatibleSource interface {
 	BigQueryClient() *bigqueryapi.Client
-	BigQueryTokenSourceWithScope(ctx context.Context, scopes []string) (oauth2.TokenSource, error)
-	BigQueryProject() string
-	BigQueryLocation() string
+	GoogleCloudTokenSourceWithScope(ctx context.Context, scope string) (oauth2.TokenSource, error)
+	GoogleCloudProject() string
+	GoogleCloudLocation() string
 	GetMaxQueryResultRows() int
 	UseClientAuthorization() bool
 	IsDatasetAllowed(projectID, datasetID string) bool
@@ -194,7 +194,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 		}
 	} else {
 		// Get a token source for the Gemini Data Analytics API.
-		tokenSource, err := source.BigQueryTokenSourceWithScope(ctx, nil)
+		tokenSource, err := source.GoogleCloudTokenSourceWithScope(ctx, "")
 		if err != nil {
 			return nil, util.NewClientServerError("failed to get token source", http.StatusInternalServerError, err)
 		}
@@ -233,8 +233,8 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	}
 
 	// Construct URL, headers, and payload
-	projectID := source.BigQueryProject()
-	location := source.BigQueryLocation()
+	projectID := source.GoogleCloudProject()
+	location := source.GoogleCloudLocation()
 	if location == "" {
 		location = "us"
 	}

internal/tools/bigquery/bigquerygetdatasetinfo/bigquerygetdatasetinfo.go

@@ -49,7 +49,7 @@ func newConfig(ctx context.Context, name string, decoder *yaml.Decoder) (tools.T
 }
 
 type compatibleSource interface {
-	BigQueryProject() string
+	GoogleCloudProject() string
 	UseClientAuthorization() bool
 	IsDatasetAllowed(projectID, datasetID string) bool
 	BigQueryAllowedDatasets() []string
@@ -84,7 +84,7 @@ func (cfg Config) Initialize(srcs map[string]sources.Source) (tools.Tool, error)
 		return nil, fmt.Errorf("invalid source for %q tool: source %q not compatible", resourceType, cfg.Source)
 	}
 
-	defaultProjectID := s.BigQueryProject()
+	defaultProjectID := s.GoogleCloudProject()
 	projectDescription := "The Google Cloud project ID containing the dataset."
 	datasetDescription := "The dataset to get metadata information. Can be in `project.dataset` format."
 	var datasetParameter parameters.Parameter

internal/tools/bigquery/bigquerygettableinfo/bigquerygettableinfo.go

@@ -50,7 +50,7 @@ func newConfig(ctx context.Context, name string, decoder *yaml.Decoder) (tools.T
 }
 
 type compatibleSource interface {
-	BigQueryProject() string
+	GoogleCloudProject() string
 	UseClientAuthorization() bool
 	IsDatasetAllowed(projectID, datasetID string) bool
 	BigQueryAllowedDatasets() []string
@@ -85,7 +85,7 @@ func (cfg Config) Initialize(srcs map[string]sources.Source) (tools.Tool, error)
 		return nil, fmt.Errorf("invalid source for %q tool: source %q not compatible", resourceType, cfg.Source)
 	}
 
-	defaultProjectID := s.BigQueryProject()
+	defaultProjectID := s.GoogleCloudProject()
 	projectDescription := "The Google Cloud project ID containing the dataset and table."
 	datasetDescription := "The table's parent dataset."
 	var datasetParameter parameters.Parameter

internal/tools/bigquery/bigquerylistdatasetids/bigquerylistdatasetids.go

@@ -48,7 +48,7 @@ func newConfig(ctx context.Context, name string, decoder *yaml.Decoder) (tools.T
 }
 
 type compatibleSource interface {
-	BigQueryProject() string
+	GoogleCloudProject() string
 	UseClientAuthorization() bool
 	BigQueryAllowedDatasets() []string
 	RetrieveClientAndService(tools.AccessToken) (*bigqueryapi.Client, *bigqueryrestapi.Service, error)
@@ -92,7 +92,7 @@ func (cfg Config) Initialize(srcs map[string]sources.Source) (tools.Tool, error)
 		projectParameterDescription = "The Google Cloud project to list dataset ids."
 	}
 
-	projectParameter = parameters.NewStringParameterWithDefault(projectKey, s.BigQueryProject(), projectParameterDescription)
+	projectParameter = parameters.NewStringParameterWithDefault(projectKey, s.GoogleCloudProject(), projectParameterDescription)
 
 	params := parameters.Parameters{projectParameter}
 

internal/tools/bigquery/bigquerylisttableids/bigquerylisttableids.go

@@ -50,7 +50,7 @@ func newConfig(ctx context.Context, name string, decoder *yaml.Decoder) (tools.T
 }
 
 type compatibleSource interface {
-	BigQueryProject() string
+	GoogleCloudProject() string
 	UseClientAuthorization() bool
 	IsDatasetAllowed(projectID, datasetID string) bool
 	BigQueryAllowedDatasets() []string
@@ -85,7 +85,7 @@ func (cfg Config) Initialize(srcs map[string]sources.Source) (tools.Tool, error)
 		return nil, fmt.Errorf("invalid source for %q tool: source %q not compatible", resourceType, cfg.Source)
 	}
 
-	defaultProjectID := s.BigQueryProject()
+	defaultProjectID := s.GoogleCloudProject()
 	projectDescription := "The Google Cloud project ID containing the dataset."
 	datasetDescription := "The dataset to list table ids."
 	var datasetParameter parameters.Parameter

internal/tools/bigquery/bigquerysearchcatalog/bigquerysearchcatalog.go

@@ -50,7 +50,7 @@ func newConfig(ctx context.Context, name string, decoder *yaml.Decoder) (tools.T
 
 type compatibleSource interface {
 	MakeDataplexCatalogClient() func() (*dataplexapi.CatalogClient, bigqueryds.DataplexClientCreator, error)
-	BigQueryProject() string
+	GoogleCloudProject() string
 	UseClientAuthorization() bool
 }
 
@@ -218,7 +218,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 
 	req := &dataplexpb.SearchEntriesRequest{
 		Query:          fmt.Sprintf("%s %s", prompt, constructSearchQuery(projectIds, datasetIds, types)),
-		Name:           fmt.Sprintf("projects/%s/locations/global", source.BigQueryProject()),
+		Name:           fmt.Sprintf("projects/%s/locations/global", source.GoogleCloudProject()),
 		PageSize:       pageSize,
 		SemanticSearch: true,
 	}
@@ -238,7 +238,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 
 	it := catalogClient.SearchEntries(ctx, req)
 	if it == nil {
-		return nil, util.NewClientServerError(fmt.Sprintf("failed to create search entries iterator for project %q", source.BigQueryProject()), http.StatusInternalServerError, nil)
+		return nil, util.NewClientServerError(fmt.Sprintf("failed to create search entries iterator for project %q", source.GoogleCloudProject()), http.StatusInternalServerError, nil)
 	}
 
 	var results []Response

internal/tools/conversationalanalytics/conversationalanalyticsaskdataagent/conversational-analytics-ask-data-agent.md

@@ -0,0 +1,60 @@
+---
+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:
+
+- conversational-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
+    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. |