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.
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.
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. - 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.
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 details of a specific data agent. |
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 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. |
Additional resource
- Conversational Analytics API reference documentation: Provides detailed descriptions of methods, endpoints, and type definitions for request and response structures.