Create data agents

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.

Conversational data agents let you interact with your database data using a natural language interface. By building these agents, you help users "talk to their data," unlocking insights from operational databases without requiring them to write complex SQL queries.

At a high level, a data agent is a combination of persona, a set of data sources, with access to a set of business knowledge critical for its purposes.

For application developers, these agents provide the following benefits:

• High accuracy: by using authored context, you can achieve high accuracy for specific business questions. Authored context is the primary key factor that agent creators can use to improve accuracy. It includes schema descriptions, system instructions, and structured context that provides additional information about expected database queries.
• Reduced complexity: agents translate natural language into SQL queries, execution, and even data summarization or visualization.
• Flexibility: you can draft agents for personal testing, or you can publish them to make them available to other users in your project or programmatically using the API.

Before you begin

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

2. Enable the AlloyDB for PostgreSQL, 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 one of the following Conversational Analytics API Identity and Access Management (IAM) roles:

• Query data from supported database sources using the QueryData method: Gemini Data Analytics Data Query User (roles/geminidataanalytics.queryDataUser) at the project level.
• Create your own data agents in the project: Gemini Data Analytics Data Agent Creator (roles/geminidataanalytics.dataAgentCreator) at the project level. This role automatically grants you the Gemini Data Analytics Data Agent Owner role on the data agents that you create.
• Edit, share, and delete all data agents in the project: Gemini Data Analytics Data Agent Owner (roles/geminidataanalytics.dataAgentOwner) at the project level.
• View and edit all data agents in the project: Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor) at the project level.
• View all data agents in the project: Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer) at the project level.

Additionally, you must have the following roles to create or edit a data agent:

• An IAM user or service account added to the cluster at the database level. For more information, see Manage database users.
• The alloydb.databaseUser role and the serviceusage.serviceUsageConsumer permission granted to the IAM user at the project level. For more information, see Add IAM policy binding for a project.

To work with AlloyDB resources, such as viewing tables or running queries, see IAM roles and permissions for AlloyDB.

Create a data agent

The following sections describe how to create a data agent. After you create an agent, you can edit its settings.

Configure basics

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

   Go to AlloyDB

2. Select a cluster from the list.

3. In the navigation menu, click Agents.

4. Click the Agents tab.

5. Select a database and sign in using your IAM account.

6. Click New agent. The New agent page opens.

7. In the Editor section, in the Agent name field, enter a descriptive name for the data agent—for example, Q4 sales data or User activity logs.

8. In the Agent description field, enter a description of the data agent. A good description explains what the agent does, what data it uses, and helps you determine if this is the correct data agent to use for a conversation—for example, What are the top 10 selling products in Q2?

9. In the Knowledge sources section, click Add source. The Add data page opens.

10. Select tables that the agent will focus on when answering questions. To view additional knowledge sources, select Show more.

11. Click Add. The new agent page reopens.

Customize table and field descriptions

To improve conversational data agent accuracy, you can optionally provide additional table metadata. Only the data agent uses this metadata, and it doesn't affect the source table. You can add the following metadata:

• Schema descriptions: add descriptions for your tables and columns to help the agent understand your data. If you don't add descriptions, the agent uses the schema descriptions from your data definitions.

Follow these best practices when you add table and field descriptions:

• Add descriptions to your data definition rather than just to your data agent definition. This makes sure that other agents also benefit from the descriptions.
• To prototype the appropriate description to help data agents understand your data, add descriptions to your specific agent. After you verify that the description has the intended impact, then you can decide whether to add the description in your data definition.

To configure table and field descriptions, follow these steps:

1. In the Agent Catalog tab, open the agent that you want to customize.
2. Click Edit Agent.
3. In Knowledge Sources, find the table you want to customize and then click Customize.
4. Enter a table description.
5. To edit any field description, click Edit next to the field. The Edit field pane opens.
   1. In the ID field, enter a field description.
   2. To save the field description, click Update.
6. To save the description and field updates, click Update. The new agent page reopens.
7. Repeat these steps for each table that you want to customize.

Add labels to data agents

In the Agent Settings section, you can create labels to organize your Google Cloud resources. Labels are key-value pairs that let you group related objects together or with other Google Cloud resources.

1. In the Agent Catalog tab, open the agent to which you want to add a label.
2. Click Edit Agent.
3. In the Agent Settings section, click Add label. The Manage labels pane opens.
4. Click Add label.
5. In the key and value fields, enter your key-value pair for the label.
6. If you want to add more labels, click Add label again.
7. To delete a label, click delete.
8. When you're finished, click Add. The new agent page reopens.

Continue to the next section to place the agent in draft mode or to publish the agent.

Preview and publish the agent

1. In the Preview section, enter an example question in the Ask a question field, and then press Enter.

   To verify that the data agent returns the data that you expect, review the agent's response. If the response is not what you expect, change the settings in the Editor section to refine the data agent configuration until you get satisfactory responses. You can continue to test and modify your agent to refine the agent's results.

2. Click Save.

3. To place the data agent in draft mode, which you can re-edit later, click Go back to return to the Agent Catalog page. Because your agent is now in draft mode, it appears in the My draft agents section on the Agent Catalog tab.

   To publish your agent, remain on the agent creation page and proceed to the next step.

4. To publish the data agent and make it available for use in the project, click Publish. Publishing the agent lets other users— who have access to the same database tables—view and converse with your agent, benefiting from the instructions and context that you created.

   You can create conversations with the data agent by using the Agents page in the Google Cloud console. You can also build your own interface to chat with the data agent by using the Conversational Analytics API.

5. Optional: In the Your agent has been published dialog, click Share to share the data agent with other users.

   1. In the Share permissions pane, click Add principal.
   2. In the New principals field, enter one or more principals.
   3. Click the Select a role list.
   4. In the Role list, select one of the following roles:
      • Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser): grants permission to chat with the data agent.
      • Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor): grants permission to edit the data agent.
      • Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer): grants permission to view the data agent.

6. Click Save.

7. To return to the new agent page, click Close. After you save or publish your agent, you can see it in the Agent Catalog.

Manage data agents

You can find existing agents in the Agent Catalog tab, which consists of three sections:

• My agents: a list of all agents that you create and publish. You can modify and share published agents with others.
• My draft agents: agents that you haven't published yet. You can't share draft agents.
• Shared by others in your organization: agents that others create and share with you. If others grant you permissions, you can edit these shared agents.

Edit a data agent

To edit a data agent, follow these steps:

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

   Go to AlloyDB

2. Select a cluster from the list.

3. In the navigation menu, click Agents.

4. Sign in to Agents using Identity and Access Management (IAM) authentication.

5. Click the Agent Catalog tab.

6. Locate the agent card of the data agent that you want to modify.

7. To open the data agent in the agent editor, click Open actions and then click Edit on the agent card.

8. Edit the data agent's configuration as needed.

9. To save your changes without publishing, click Save.

10. To publish your changes, click Publish. In the Share dialog, you can either share the agent with others, or you can click Cancel.

11. To return to the Agents pane, click Go back.

Share a data agent

Follow these steps to share a published data agent. You can't share draft agents.

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

   Go to AlloyDB

2. Select a cluster from the list.

3. In the navigation menu, click Agents.

4. Sign in to Agents using Identity and Access Management (IAM) authentication.

5. Click the Agent Catalog tab.

6. Locate the agent card of the data agent that you want to modify.

7. To open the data agent in the agent editor, click Open actions > click Edit on the agent card.

8. To share the data agent with other users, click Share.

9. In the Share permissions pane, click Add principal.

10. In the Add principals field, enter one or more principals.

11. Click Select a role.

12. In the Role list, select one of the following roles:

    • Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser): grants permission to chat with the data agent.
    • Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor): grants permission to edit the data agent.
    • Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer): grants permission to view the data agent.

13. Click Save.

14. To return to the agent editing page, click Close.

15. To return to the Agents pane, click Go back.

Delete a data agent

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

   Go to AlloyDB

2. Select a cluster from the list.

3. In the navigation menu, click Agents.

4. Sign in to Agents using Identity and Access Management (IAM) authentication.

5. Select the Agent Catalog tab.

6. In the Agents section of the Agent Catalog tab, locate the agent card of the data agent that you want to delete.

7. Click Open actions > Delete.

8. In the Delete agent? dialog, click Delete. Deleting the agent permanently removes the agent from the project.

   After you delete an agent, existing conversations are available in view-only mode. You can't ask new questions of the deleted agent.

Locations

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

What's next

• Learn more about conversational analytics in AlloyDB.
• Learn more about the Conversational Analytics API.
• Analyze data with conversations.
• Learn more about how the Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer) role grants permission to view the data agent.