Create data agents

This document describes how to create, edit, and delete data agents in BigQuery. Data agents contain table metadata and use case-specific query processing instructions that define the best way to answer user questions about a set of tables that you select. Users can have conversations with data agents to ask questions about BigQuery data using natural language.

Before you begin

1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

   Go to project selector

2. Verify that billing is enabled for your Cloud de Confiance project.

3. Enable the BigQuery, Gemini Data Analytics, and Gemini for Cloud de Confiance by S3NS API 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 IAM roles:

• Create, edit, share, and delete all data agents in the project: Gemini Data Analytics Data Agent Owner (roles/geminidataanalytics.dataAgentOwner) on the project.
• Create, edit, share, and delete your own data agents in the project: Gemini Data Analytics Data Agent Creator (roles/geminidataanalytics.dataAgentCreator) on the project. Users with this role are automatically granted the Gemini Data Analytics Data Agent Owner role on the data agents that they create.
• 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)

Additionally, any user that creates or edits a data agent must have the following roles:

• BigQuery Data Viewer (roles/bigquery.dataViewer) on any table that the data agent uses as a data source.
• DataCatalog Search Admin (roles/datacatalog.searchAdmin) on the project.
• If a data source table uses column-level access control, Fine-Grained Reader (roles/datacatalog.categoryFineGrainedReader) on the appropriate policy tag. For more information, see Roles used with column-level access control.
• If a data source table uses row-level access control, you must be granted the role-level access policy on that table. For more information, see Create or update row-level access policies.
• If a data source table uses data masking, Masked Reader (roles/bigquerydatapolicy.maskedReader) on the appropriate data policy. For more information, see Roles for querying masked data.

Generate insights

Optionally, generate insights for any table that you want to use as a data source. Generated insights provide table metadata that the data agent can use to help generate responses to user questions. For more information, see Generate insights for a BigQuery table.

If you don't generate insights beforehand, they are automatically generated when you select a table as a data source when you are creating a data agent.

Create a data agent

Follow these steps to create a data agent:

1. Go to the BigQuery Agents page.

   Go to the Agents page

2. Select the Agents tab.

3. Click New agent. The New agent page opens.

4. In the Editor section, in the Agent name field, type a descriptive name for the data agent.

5. In the Agent description field, type a description of the data agent. A good description helps users to know when this is the right data agent to chat with.

6. In the Data sources section, click Add data. The Add data page opens.

7. In the Recents section, select any tables that you want to use as data sources.

8. Optional: Add a table that isn't listed in the Recents section:

   1. In the Search section, type the table name into the Search for tables field, and then press Enter. The table name doesn't need to be exact.
   2. In the Search results section, select one or more tables.

9. Click Add data. The new agent page reopens.

10. Optional: To improve data agent accuracy, you can provide additional table metadata. This metadata is only used by the data agent and doesn't affect the source table.

    1. In the Data sources section, click Improve accuracy on a table.
    2. Create a table description. You can type a description in the Table Description field, or accept the suggestion from Gemini.
    3. In the Fields section, review the Gemini-suggested field descriptions. Select any that you want to accept and click Accept suggestions. Select any that you want to reject and click Reject suggestions.

    4. Manually edit any field description by clicking edit Edit next to the field. The Edit field pane opens.

    5. In the Description field, type a field description.

    6. Click Update.

    7. Click Update. The new agent page reopens.

11. In the Instructions section, type instructions for the data agent in the Agent instructions field. The data agent uses these instructions to understand the context for user questions. For example, instructions might include the following types of information:

    • Key fields: the most important fields for analysis.
    • Synonyms: alternative terms for key fields.
    • Excluded fields: fields that the data agent should avoid using.
    • Filtering and grouping: fields that the agent should use to filter and group data.
    • Join relationships: how two or more tables are related to each other, and which columns are used to join them.

    Click Show examples to see examples of instructions.

12. Optional: Create golden queries for the data agent. The data agent uses golden queries to tune the data agent on the selected data sources. This helps the model used by the data agent to learn the business logic used by your organization.

    1. Select one or more Gemini-suggested golden queries:

       1. In the Golden Queries section, click Review suggestions. The Review suggested golden queries page opens.
       2. Review the suggested golden queries. Select any that apply to your use case.
       3. Click Add. The new agent page reopens.

    2. If you would like to create your own golden query, click Add query. The Add golden query page opens.

       1. In the Question field, type the user question that the golden query is meant to answer.
       2. Click Generate SQL to have Gemini generate a golden query that corresponds to the user question you specified.
       3. Modify the golden query if you choose.
       4. Click Run and verify that the query returns the results that you expect.
       5. Click Add. The new agent page reopens.

    3. Repeat these steps as needed to create additional golden queries.

13. Optional: Configure the data agent to use Python instead of SQL when generating responses to user questions. In the Settings section, click the Advanced analytics toggle.

    You should use this option when you expect the data agent to answer more complex questions that are difficult or impossible to address with SQL, like those that involve forecasting, correlations, and causation.

14. Optional: Set a size limit for the queries processed by the data agent. In the Settings section, type a value in the Maximum bytes billed field.

    If you don't specify a value, the maximum bytes billed defaults to the project's query usage per day quota. The usage per day quota is unlimited unless you have specified a custom quota.

15. In the Preview section, type an example user question in the Ask a question field and then press Enter. Review the data agent's response to verify that it returns the data that you expect. If it doesn't, change settings in the Editor action to iterate on the data agent configuration until you get satisfactory responses. You can continue to test and modify your agent to refine the agent's results.

16. Click Save.

17. To continue to iterate on the data agent, click arrow_back Go back to return to the Agents pane.

    

    Otherwise, proceed to the next step.

18. Click Publish to publish the data agent and make it available for use in the project. You can create conversations with the data agent by using BigQuery Studio, and by using Looker Studio if you have a Looker Studio subscription. You can also build your own interface to chat with the data agent by using the Conversational Analytics API.

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

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

21. In the New principals field, enter one or more principals.

22. Click the Select a role drop-down.

23. 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.

24. Click Save.

25. To return to the new agent page, click Close.

Edit a data agent

Follow these steps to edit a data agent:

1. Go to the BigQuery Agents page.

   Go to the Agents page

2. Select the Agents tab.

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

4. Click more_vert Open actions > Edit on the agent card to open the data agent in the agent editor.

5. Edit the data agent configuration as needed.

6. Click Save to save your changes.

7. Click Publish to publish your changes.

8. Click arrow_back Go back to return to the Agents pane.

   

Share a data agent

Follow these steps to share a data agent:

1. Go to the BigQuery Agents page.

   Go to the Agents page

2. Select the Agents tab.

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

4. Click more_vert Open actions > Edit on the agent card to open the data agent in the agent editor.

5. Click Share to share the data agent with other users.

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

7. In the New principals field, enter one or more principals.

8. Click the Select a role drop-down.

9. 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.

10. Click Save.

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

12. Click arrow_back Go back to return to the Agents pane.

    

Delete a data agent

Follow these steps to delete a data agent:

1. Go to the BigQuery Agents page.

   Go to the Agents page

2. Select the Agents tab.

3. In the My agents section of the Agents tab, locate the agent card of the data agent that you want to delete.

4. Click more_vert Open actions > Delete.

5. In the Delete agent? 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 BigQuery.
• Learn more about the Conversational Analytics API.
• Analyze data with conversations.