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 Google Cloud console, on the project selector page, select or create a Google Cloud 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 role ( 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 Google Cloud project .

3. Enable the BigQuery, Gemini Data Analytics, and Gemini for Google Cloud 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 Agentspage.

   Go to the Agents page

2. Select the Agentstab.

3. Click New agent. The New agentpage opens.

4. In the Editorsection, in the Agent namefield, type a descriptive name for the data agent.

5. In the Agent descriptionfield, 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 sourcessection, click Add data. The Add datapage opens.

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

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

   1. In the Searchsection, type the table name into the Search for tablesfield, and then press Enter. The table name doesn't need to be exact.
   2. In the Search resultssection, 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 sourcessection, click Improve accuracyon a table.
    2. Create a table description. You can type a description in the Table Descriptionfield, or accept the suggestion from Gemini.
    3. In the Fieldssection, 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 Editnext to the field. The Edit fieldpane opens.

    5. In the Descriptionfield, type a field description.

    6. Click Update.

    7. Click Update. The new agent page reopens.

11. In the Instructionssection, type instructions for the data agent in the Agent instructionsfield. 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 examplesto 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 Queriessection, click Review suggestions. The Review suggested golden queriespage 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 querypage opens.

       1. In the Questionfield, type the user question that the golden query is meant to answer.
       2. Click Generate SQLto have Gemini generate a golden query that corresponds to the user question you specified.
       3. Modify the golden query if you choose.
       4. Click Runand 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 Settingssection, click the Advanced analyticstoggle.

    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 Settingssection, type a value in the Maximum bytes billedfield.

    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 Previewsection, type an example user question in the Ask a questionfield 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 Editoraction 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 backto return to the Agentspane.

    

    Otherwise, proceed to the next step.

18. Click Publishto 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 publisheddialog, click Shareto share the data agent with other users.

20. In the Share permissionspane, click Add principal.

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

22. Click the Select a roledrop-down.

23. In the Rolelist, 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 Agentspage.

   Go to the Agents page

2. Select the Agentstab.

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

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

5. Edit the data agent configuration as needed.

6. Click Saveto save your changes.

7. Click Publishto publish your changes.

8. Click arrow_back Go backto return to the Agentspane.

   

Share a data agent

Follow these steps to share a data agent:

1. Go to the BigQuery Agentspage.

   Go to the Agents page

2. Select the Agentstab.

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

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

5. Click Shareto share the data agent with other users.

6. In the Share permissionspane, click Add principal.

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

8. Click the Select a roledrop-down.

9. In the Rolelist, 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 backto return to the Agentspane.

    

Delete a data agent

Follow these steps to delete a data agent:

1. Go to the BigQuery Agentspage.

   Go to the Agents page

2. Select the Agentstab.

3. In the My agentssection of the Agentstab, 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 .