Conversational Analytics API: Build data agents and chat with your data

Private Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Important: The Data QnA API is deprecated. If you're migrating from the Data QnA API, see the migration guide for an overview of key differences and required migration steps.

Developers can use the Conversational Analytics API, which is accessed through geminidataanalytics.googleapis.com, to build an artificial intelligence (AI)-powered chat interface, or data agent, that answers questions about structured data in BigQuery, Looker, and Looker Studio using natural language. With the Conversational Analytics API, you provide your data agent with business information and data ("context"), as well as access to tools such as SQL, Python, and visualization libraries. These agent responses are presented to the user and can be logged by the client application, creating a seamless and auditable data chat experience.

Learn how and when Gemini for Google Cloud uses your data.

As an early-stage technology, Gemini for Google Cloud products can generate output that seems plausible but is factually incorrect. We recommend that you validate all output from Gemini for Google Cloud products before you use it. For more information, see Gemini for Google Cloud and responsible AI.

Note: Pre-GA Preview offerings (1) are intended for use in test environments only and shouldn't be used in a production environment or to process personal data or other data subject to legal or regulatory compliance requirements, and (2) are subject to the Pre-GA Offerings Terms of the Service Specific Terms, and the Consent Addendum for Gemini for Google Cloud Trusted Tester Program.

Get started with the Conversational Analytics API

To set up your environment and begin building and interacting with data agents by using the Conversational Analytics API, you can either start with the Colaboratory notebooks for a guided experience or follow the steps in Setup and prerequisites for a self-driven experience.

Note: To use the Conversational Analytics API, you must be part of the private preview. To express interest, fill out the preview interest form.

Interactive Colaboratory notebooks

For an interactive, step-by-step guide to setting up your environment, building a data agent, and making API calls, see the following Colaboratory notebooks:

• Conversational Analytics API HTTP Colaboratory notebook
• Conversational Analytics API SDK Colaboratory notebook

Setup and prerequisites

Before you use the API or the examples, complete the following steps:

• Enable the Conversational Analytics API: Describes prerequisites to enable the Conversational Analytics API.
• Grant Conversational Analytics API IAM roles and permissions: Describes the predefined IAM roles for managing access to data agents.
• Authenticate and connect to a data source with the Conversational Analytics API: Provides instructions for authenticating to the API and configuring connections to your BigQuery, Looker, and Looker Studio data.

Build and interact with a data agent

After completing the previous steps, use the Conversational Analytics API to build and interact with a data agent by following these steps:

• Build a data agent using HTTP: Provides a complete example of building and interacting with a data agent by using direct HTTP requests with Python.
• Build a data agent using the Python SDK: Provides a complete example of building and interacting with a data agent by using the Python SDK.
• Write effective system instructions: Learn how to structure the YAML content for the system_instruction parameter to guide agent behavior and improve response accuracy. You can also view examples of system instructions in BigQuery data sources and in Looker data sources.
• Render a Conversational Analytics API agent response as a visualization: Provides an example of processing chart specifications from API responses and rendering them as visualizations by using the Python SDK and the Vega-Altair library.

Best practices

• Manage BigQuery costs for your agents: Learn how to monitor and manage BigQuery costs for your Conversational Analytics API agents by setting project-level, user-level, and query-level spending limits.

Key API operations

The API provides the following core endpoints for managing data agents and conversations:

Operation	HTTP method	Endpoint	Description
Create an agent	POST	/v1alpha/projects/*/locations/*/dataAgents	Creates a new data agent.
Get an agent	GET	/v1alpha/projects/*/locations/*/dataAgents/*	Retrieves the details of a specific data agent.
Get Identity and Access Management policy	POST	/v1alpha/projects/*/locations/*/dataAgents/*:getIamPolicy	Gets the Identity and Access Management permissions that are assigned to each user for a specific data agent. Users with a Data Agent Owner role can call this endpoint to view the data agent's Identity and Access Management policy before using the setIAMpolicy endpoint to share a data agent with other users.
Set Identity and Access Management policy	POST	/v1alpha/projects/*/locations/*/dataAgents/*:setIamPolicy	Sets the Identity and Access Management policy for a specific data agent. Users with a Data Agent Owner role should call this endpoint to share a data agent with other users, which effectively updates those users' Identity and Access Management permissions.
Update an agent	PATCH	/v1alpha/projects/*/locations/*/dataAgents/*	Modifies an existing data agent.
List agents	GET	/v1alpha/projects/*/locations/*/dataAgents	Lists available data agents in a project.
Delete an agent	DELETE	/v1alpha/projects/*/locations/*/dataAgents/*	Removes a data agent.
Create a conversation	POST	/v1alpha/projects/*/locations/*/conversations	Starts a new, persistent conversation.
Chat by using a conversation reference	POST	/v1alpha/projects/*/locations/*:chat	Continues a stateful conversation by sending a chat message that references an existing conversation and its associated agent context. For multi-turn conversations, Google Cloud stores and manages the conversation history.
Chat by using a data agent reference	POST	/v1alpha/projects/*/locations/*:chat	Sends a stateless chat message that references a saved data agent for context. For multi-turn conversations, your application must manage and provide the conversation history with each request.
Chat by using inline context	POST	/v1alpha/projects/*/locations/*:chat	Sends a stateless chat message by providing all context directly in the request, without using a saved data agent. For multi-turn conversations, your application must manage and provide the conversation history with each request.
Get a conversation	GET	/v1alpha/projects/*/locations/*/conversations/*	Retrieves the details of a specific conversation.
List conversations	GET	/v1alpha/projects/*/locations/*/conversations	Lists the conversations in a specific project.
List messages in a conversation	GET	/v1alpha/projects/*/locations/*/conversations/*/messages	Lists messages within a specific conversation.

Send feedback

Use the following links to file a bug or request a feature.

• File a bug report
• File a feature request

Additional resource

• Conversational Analytics API reference documentation: Provides detailed descriptions of methods, endpoints, and type definitions for request and response structures.