Create data agents

This document describes how to create, edit, manage, and delete data agents in BigQuery.

In BigQuery, you can have conversations with data agents to ask questions about BigQuery data using natural language. 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 knowledge sources, such as tables, views, or user-defined functions (UDFs) that you select.

Before you begin

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

  2. Enable the BigQuery, Gemini Data Analytics, Gemini for Google Cloud, and Knowledge Catalog APIs.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

Required roles

To work with data agents, you must have Identity and Access Management (IAM) permissions that match your use case. The following sections list required roles based on whether you are creating and publishing agents, provisioning agents in Gemini Enterprise, or discovering and using agents across various surfaces. For more information, see Conversational Analytics API IAM 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.
  • 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 interact with the Gemini-powered chat interface in Data Studio: BigQuery Studio User (roles/bigquery.studioUser) or Gemini for Google Cloud User (roles/cloudaicompanion.user), each of which provide the cloudaicompanion.topics.create permission. Grant these roles at the project level. Users also require the Data Studio Asset Viewer (roles/datastudio.viewer) role.
  • Add knowledge sources to an agent:
    • Data Catalog Viewer (roles/datacatalog.viewer) on the project.

To have conversations, see the required roles for conversations.

Agents act on your behalf and uses your permissions. Agents can only access data and resources that you have permission to access.

Best practices

Conversational analytics automatically runs queries on your behalf to answer your questions. Consider the following factors that might increase query cost:

  • Large table sizes
  • Use of data joins in queries
  • Frequent calls to AI functions within queries

Generate insights

You can optionally generate data insights in Knowledge Catalog for any table that you want to use as a knowledge source.

Generated insights provide table metadata that the data agent can use to help generate responses to your questions.

If you don't generate insights beforehand, the system automatically generates them when you select a table as a knowledge source while creating a data agent.

Work with the sample data agent

If you're unfamiliar with configuring agents for conversational analytics, you can optionally view the predefined sample agent generated for every Google Cloud project. You can chat with it and view its parameters to see how it was created, but you can't modify it.

To view the sample agent, do the following:

  1. In the Google Cloud console, go to the BigQuery Agents page.

    Go to Agents

  2. Select the Agent catalog tab.

  3. Under the section Sample agents by Google, click the sample agent card.

Create a data agent

The following sections describe how to create a data agent.

After you create an agent, you can edit its settings.

Initial steps

  1. In the Google Cloud console, go to the BigQuery Agents page.

    Go to Agents

  2. Select the Agent catalog 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—for example, Q4 sales data or User activity logs.

  5. In the Agent description field, type a description of the data agent. A good description explains what the agent does, what data it uses, and helps you know when this is the right data agent to chat with—for example, Ask questions about customer orders and revenue.

  6. In the Knowledge sources section, click Add source. The Add knowledge source page opens.

  7. In the Recents section, select any tables, views, graphs, or UDFs that you want to use as knowledge sources. UDFs are prefixed with an 'fx' indicator in the Google Cloud console.

  8. To view additional knowledge sources, select Show more.

  9. Optional: Add a knowledge source that isn't listed in the Recents section:

    1. In the Search section, type the source name into the Search for tables field, and then press Enter. The source name doesn't need to be exact.

    2. In the Search results section, select one or more sources.

  10. Click Add. The new agent page reopens.

Customize table and field descriptions

To improve 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.

Follow these best practices when you create a table and field descriptions:

  • Use these descriptions as a guide to understand how the data agent understands the schema. If the descriptions suggested by the agent are correct, you can accept them.

  • If the data agent doesn't show an understanding of the schema after you configure these descriptions, then manually adjust the descriptions to provide the correct information.

Follow these steps to configure table and field descriptions:

  1. In the Knowledge sources section, click the Customize link for 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.

  4. Select any field descriptions that you want to accept and click Accept suggestions. Select any descriptions that you want to reject and click Reject suggestions.

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

    1. In the Description field, type 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 needs customization.

Create agent instructions

The agent should understand context for user questions without needing any custom instructions. Create custom instructions for the agent only if you need to change the agent's behavior or improve the context in ways that aren't already supported by other context features—for example, custom table and field metadata, or verified queries.

In the Instructions section, type instructions for the data agent in the Agent instructions field. Because the data agent uses these instructions to understand the context for user questions and to provide answers, make the instructions as clear as possible.

If you don't get a satisfactory answer from the agent, then add structured context such as descriptions, examples or glossary terms. If you still don't get a satisfactory answer, add custom instructions like the examples in the following table.

For even more examples of instructions, click Show examples.

Information type Description Examples
Key fields The most important fields for analysis. "The most important fields in this table are: Customer ID, Product ID, Order Date."
Filtering and grouping Fields that the agent should use to filter and group data. "When a question is about a timeline or 'over time,' always use the order_created_date column." "When someone says 'by product,' group by the product_category column."
Default filtering Fields to filter on by default. "Unless stated otherwise, always filter the data on order_status = 'Complete'."
Synonyms and business terms Alternative terms for key fields. "If someone asks about 'Revenue' or 'Sales', use the total_sale_amount column." "We consider 'loyal' customers to be those with purchase_count > 5."
Excluded fields Fields that the data agent should avoid using. "Never use these fields: Transaction Date Derived, City Derived."
Join relationships How two or more tables are related to each other, and which columns are used to join them. The agent must use standard SQL JOINs on column pairs to combine data. See the example column. Customer Activity
  • order_items.user_id = users.id
    (to link sales to customers)
  • events.user_id = users.id
    (to link website activity to logged-in customers)

Create verified queries

An agent uses verified queries in two ways:

  • If an agent can use a verified query to answer a question that you ask it, to ensure a trustworthy answer, the agent invokes the query exactly as written.
  • If the agent can't use the verified query to answer a question, it still uses the query as a reference to understand the data and the best practices for querying it.

You can select verified queries from a list generated by the system, or create your own.

To create a verified query for the data agent, formerly known as a golden query, do the following:

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

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

  2. To create your own verified query, click Add query. The Add verified query page opens.