Analyze data with conversations

Preview

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

This document describes how to create, edit, and delete conversations in Spanner. Conversations are persisted chats with a data agent.

You can ask data agents multi-part questions that use common terms—for example, "sales" or "most popular"—without specifying table field names, or defining conditions to filter the data. The chat response provides the answer to your question as text and code, and it generates charts when appropriate. The response includes the reasoning behind the results.

You can create a conversation with a data agent. When you create a direct conversation, the Conversational Analytics API interprets your question without the context and processing instructions offered by a data agent.

Before you begin

1. Verify that billing is enabled for your Google Cloud project.

2. Enable the Spanner, Data Analytics API with Gemini, and Gemini for Google Cloud APIs.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the APIs

Required roles

To work with data agents, you must have IAM permissions that match your use case. The following table lists required roles based on whether you're creating and publishing agents, provisioning agents in Gemini Enterprise, or discovering and using agents. For more information, see Conversational Analytics API Identity and Access Management roles.

Use case	Required roles
Create, edit, publish, share, and delete agents	To create data agents in a project: Gemini Data Analytics Data Agent Creator (roles/geminidataanalytics.dataAgentCreator) on the project. This role automatically grants you the Gemini Data Analytics Data Agent Owner role on the data agents that you create. To edit, share, or delete a data agent: Gemini Data Analytics Data Agent Owner (roles/geminidataanalytics.dataAgentOwner) on the agent or project. To edit a data agent in a project: Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor) on the project. To view data agents in a project: Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer) on the project. Additionally, you must have the following roles to create or edit a data agent: An IAM user or service account added to the cluster. For more information, see Apply IAM roles. The spanner.databaseReader role granted to the IAM user at the project level. For more information, see Add IAM policy binding for a project. Roles and permissions granted to the IAM user at the project level for the required databases. For more information, see Grant roles and permissions.
Provision agents in Gemini Enterprise	To make a published agent available to users in Gemini Enterprise, you need permissions to register and manage A2A agents in the Gemini Enterprise administration console.
Discover and use agents	To chat with data agents: Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser). To view all data agents in the project: Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer).

To work with Spanner resources, see Spanner roles and permissions.

Create conversations

You can create persistent conversations with an agent or with a data source in the Google Cloud console for Spanner from the Agent Catalog tab on the Agents page.

Create a conversation with a data agent

To create a conversation with a data agent, you first create a data agent and publish it. You can also initiate a conversation with agents that others share with you.

To create a conversation with a data agent in the Google Cloud console, follow these steps:

1. In the Google Cloud console, go to the Spanner page.

   Go to Spanner

2. Select an instance from the list, and then select a database.

3. In the navigation menu, click Agents.

4. From either the My agents or Shared by others in your organization section, click the agent card of the agent that you want to chat with.

5. Click Start a Conversation. A new chat panel opens.

6. In the Ask a question field, enter a question for the data agent. For example, "What were our total sales last quarter?" or "Show me the top 5 users by session time." You can also click one of the Gemini-suggested questions to get started.

   The data agent responds by stating the action that it's taking to address your question, and then the data agent returns the results.

   To see each step that the data agent takes to provide the answer to your question, click Show reasoning to view each message in the agent's reasoning process.

   To see information about how the results were calculated, click How was this calculated? The Summary section now includes a generated query followed by the query result. You can copy the code and then click Studio to paste the code in the query editor.

   When appropriate for the data, the data agent provides charts, tables, and other visualizations. To view your chat history, go to the Conversation Management list.

   To view agent information, go to the Details panel. This panel includes a description of the agent and its knowledge sources.

Manage conversations

You can open, rename, or delete a conversation on the Agents page.

Open an existing conversation

1. In the Google Cloud console, go to the Spanner page.

   Go to Spanner

2. Select an instance from the list, and then select a database.

3. In the navigation menu, click Agents.

4. On the Conversations tab, in the conversations list, click the conversation you want to open.

Rename a conversation

1. In the Google Cloud console, go to the Spanner page.

   Go to Spanner

2. Select an instance from the list, and then select a database.

3. In the navigation menu, click Agents.

4. On the Conversations tab, in the conversations list, click the conversation you want to rename.

5. Click View actions > Rename.

6. In the Rename conversation dialog, enter a new name for the conversation in the Conversation name field.

7. Click Rename.

Delete a conversation

1. In the Google Cloud console, go to the Spanner page.

   Go to Spanner

2. Select an instance from the list, and then select a database.

3. In the navigation menu, click Agents.

4. On the Conversations tab, in the conversations list, click the conversation you want to delete.

5. Click View actions > Delete.

6. In the Delete conversation? dialog, click Delete.

Locations

Conversational analytics operates globally; you can't choose which region to use.

What's next

• Learn more about conversational analytics in Spanner.
• Learn more about the Conversational Analytics API.
• Create a data agent in Spanner.