# Create data agents

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

In BigQuery, you can have
[conversations](https://docs.cloud.google.com/bigquery/docs/create-conversations.md.txt)
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](https://docs.cloud.google.com/billing/docs/how-to/verify-billing-enabled.md.txt#confirm_billing_is_enabled_on_a_project).

2.


   Enable the BigQuery, Gemini Data Analytics,
   Gemini for Google Cloud, and Knowledge Catalog APIs, if any are not already enabled.


   **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](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).

   [Enable the APIs](https://console.cloud.google.com/apis/enableflow?apiid=bigquery.googleapis.com,geminidataanalytics.googleapis.com,cloudaicompanion.googleapis.com,dataplex.googleapis.com)

### 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](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/access-control).

- **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 custom
    agents](https://docs.cloud.google.com/gemini/enterprise/docs/register-and-manage-an-a2a-agent) and configure an [Agent Gateway](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/agent-gateway-overview.md.txt) 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.
- **Configure and view conversation logs:**
  - To create the log dataset and grant access in the agent's project: `bigquery.datasets.create`, and BigQuery Data Owner (`roles/bigquery.dataOwner`) or BigQuery Admin (`roles/bigquery.admin`) on the log dataset.
  - To change an agent's conversation logging settings: `geminidataanalytics.dataAgents.update`, included in [Gemini Data
    Analytics Data Agent
    Editor](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/access-control#data-agent-editor) (`roles/geminidataanalytics.dataAgentEditor`).
  - For the Conversational Analytics API service agent (`service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com`) to create the log table and write rows: BigQuery Data Editor (`roles/bigquery.dataEditor`) on the log dataset. If the log dataset uses [customer-managed Cloud KMS
    keys](https://docs.cloud.google.com/bigquery/docs/customer-managed-encryption) (CMEK), grant the BigQuery encryption service account (`bq-PROJECT_NUMBER@bigquery-encryption.iam.gserviceaccount.com`) the Cloud KMS CryptoKey Encrypter/Decrypter (`roles/cloudkms.cryptoKeyEncrypterDecrypter`) role on the Cloud KMS key.
  - For analysts who query conversation logs: BigQuery Data Viewer (`roles/bigquery.dataViewer`) on the log dataset and BigQuery Job User (`roles/bigquery.jobUser`) on a project to run queries.

To have conversations, see the [required roles for conversations](https://docs.cloud.google.com/bigquery/docs/create-conversations.md.txt#required_roles).

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](https://docs.cloud.google.com/knowledge-catalog/docs/data-insights-structured-data.md.txt) 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](https://console.cloud.google.com/bigquery/agents_hub)
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](https://docs.cloud.google.com/bigquery/docs/create-data-agents.md.txt#edit-agent).

> [!NOTE]
> **Note:** If you're in a conversation with a data source, you can also [create
> an agent](https://docs.cloud.google.com/bigquery/docs/create-conversations#create-agent-from-conversation) from that conversation.

### Initial steps

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

   [Go to Agents](https://console.cloud.google.com/bigquery/agents_hub)
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.

> [!NOTE]
> **Note:** If your changes to descriptions aren't reflected in the Google Cloud console, you can use the [`list`](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations.dataAgents/list.md.txt) method to verify or the [`patch`](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations.dataAgents/patch.md.txt) method to update the descriptions.

### 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 GoogleSQL 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.

> [!NOTE]
> **Note:** To create a parameterized verified query, see [Create parameterized verified queries](https://docs.cloud.google.com/bigquery/docs/create-data-agents.md.txt#create-param-verified-queries).

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.

   1. In the **Question** field, type the user question that the verified query answers.
   2. Click **Generate SQL** to have Gemini generate a verified query that corresponds to the user question that you specified.
   3. Modify the verified 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 verified queries.

### Create parameterized verified queries

Parameterized verified queries extract values from a user's question for the
conversational analytics agent and provide tailored results.

Analysts and builders can create reusable SQL templates that contain
placeholders for these values. The templates dynamically substitute parameters
at runtime to answer a wider range of user questions than do regular verified
queries.

When a user asks a question that matches the template's pattern, the
conversational analytics agent extracts parameter values from the question---
for example, product name, region, and date. It then injects these values into
the [parameterized query](https://docs.cloud.google.com/bigquery/docs/parameterized-queries.md.txt).
Matching responses from the query template appear
as **verified**.

Parameterized verified queries significantly enhance the power and flexibility
of verified queries. They ensure consistent, trusted answers across various
inputs and reduce the number of individual queries to maintain.

#### How it works

An expert, such as a data analyst, defines a verified query by using a template
question---for example, "What were the sales for `@product` in `@region`?" Then,
the expert creates or modifies the verified query using SQL parameters, as
the following example shows:

```googlesql
SELECT * FROM sales WHERE region = @region AND product = @product
```

After the verified query is saved, a user can ask the conversational analytics
agent a question in natural language; for example, "What were the sales for
laptops in North America?"

To answer the user's question, the agent performs the following
steps:

1. Matches the question to the pattern associated with the parameterized verified query. The agent uses [natural language understanding
   (NLU)](https://wikipedia.org/wiki/Natural_language_understanding) to identify and extract the values for `@region` (North America) and `@product` (laptops) from the user's question.
2. Substitutes the extracted values into the `@region` and `@product` placeholders in the SQL template.
3. Runs the complete SQL query; for example, `SELECT * FROM sales WHERE
   region = 'North America' AND product = 'Laptops'`.
4. Returns the results to the user. Matches are always marked as **verified**.

#### Tips for creating effective parameterized queries

- **Use clear parameter names** . Use descriptive names for parameters---for example, `@start_date` instead of `@d1`.
- **Create detailed parameter descriptions** . The large language model (LLM) for conversational analytics uses parameter descriptions to identify the parameters and their values from user questions. For example, `num_enrollments` is an effective parameter name, but `number of student
  enrollments from ages 5-14` is a parameter description that gives more context about the query.
- **Ensure consistent data typing**. Ensure that the data types expected by the SQL query match the data types likely to be extracted from the user's question.
- **Provide a well-defined scope**. Create templates for common and important question patterns where the query construction is complex, or the logic is unintuitive. Doing so helps the LLM return optimal results.
- **Test thoroughly**. Test with various natural language phrasings to ensure that parameters are extracted correctly.

#### Create a parameterized verified query

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

Before you create or modify a query, draft the query, considering the natural
language pattern and your question. For example, if you ask "Do we know the
total stock for organic bananas in the US-EAST warehouse?," you can rewrite the
question as the parameterized verified query as "What is the total stock for
@product in the @region warehouse?" The agent turns
this question into a SQL query that you update with default values.

To create a parameterized verified query for a data agent, you can either
create a new query when you create a new agent, or you can edit an existing
verified query for a new or existing agent.

The following instructions use a sample verified query to configure with
parameters.

##### Select an existing Gemini-suggested verified query

1. In the **Verified Queries** section of a new or existing agent, click **Review suggestions** . The **Review suggested verified queries** page opens.
2. Select the checkbox next to a suggested verified query.
3. In the query window, click **Show more** to expand the query description.
4. To open the existing query, click **Edit**.
5. To finish configuring the query, see [Configure the parameters for the
   verified query](https://docs.cloud.google.com/bigquery/docs/create-data-agents#configure-query-parameters).

##### Create an agent and then create a verified query

1. See [Initial steps](https://docs.cloud.google.com/bigquery/docs/create-data-agents.md.txt#initial-steps) and continue through the rest of the configuration steps to **Verified queries.**
2. In the Google Cloud console, in the **Verified queries** section of the new agent, click **Add query** . The **Add verified query** page opens.
3. To finish configuring the query, see [Configure the parameters for the
   verified query](https://docs.cloud.google.com/bigquery/docs/create-data-agents#configure-query-parameters).

##### Configure the parameters for the verified query

1. In the **Question** field, type the user question answered by the verified query.
2. To specify parameters, use the `@` symbol followed by a parameter name. This syntax identifies a placeholder that ingests a value from the user question. Use a natural language question that shows how the parameters will be used in user questions. For example: "What is the total stock for @product in the @region warehouse?"
3. Click **Generate SQL**. The SQL looks like the following example:

   ```sql
      SELECT
          SUM(stock) AS total_stock
      FROM
          inventory
      WHERE
          product_id = @product
          AND region = @region;
   ```
4. To add default values to the placeholders in the query, click
   **Manage query parameters** , and then click **Add query parameter**.

5. For the first parameter, four fields appear for **Name** , **Type,** **Value** , and **Description**.

   - For **Name** , copy `@product` from your question and paste it into this field.
   - For **Type** , select **STRING**.
   - For **Value** , enter `organic bananas`.
   - For **Description**, enter as specific a description as possible. For example, a product located in a regional warehouse.
6. For the second parameter, click **Add query parameter**.

   - For **Name** , copy `@region` from your question and paste it into this field.
   - For **Type** , select **STRING**.
   - For **Value** , enter `US-EAST`.
   - For **Description** , enter as specific a description as possible---for example, `a regional warehouse where products are located.`
7. When you have filled out fields for both parameters, click **Save**.

##### Test the parameterized verified query

1. Click **Run** and verify that the query returns the results that you expect.
2. To test the query for users in a later screen, copy the entire question field.
3. Click **Save** to exit the **Add query** screen and return to the agent **Edit** page.
4. On the agent **Edit** page, paste the question field, that you copied previously, into the **Preview** window.
   1. Replace the`@product` variable with `organic bananas`.
   2. Replace the `@region` variable with `US-EAST`.
5. Press enter. Check the result. In this case, a valid answer is the total stock number of the bananas in the US-EAST region---for example, 1,000.
6. To create or edit additional verified queries, repeat these steps as needed.

Now that you have saved the query, a user can ask the question
"Do we know the total stock for organic bananas in the US-EAST warehouse?"
Conversational analytics then does the following:

1. Matches this question to the pattern.
2. Extracts the `@product` parameter as `@product` = "organic bananas" and the `@region` parameter = "US-EAST" from the question.
3. Executes the query: `SELECT SUM(stock) AS total_stock FROM inventory WHERE product_id = 'organic bananas' AND region = 'US-EAST';`
4. Returns the calculated `total_stock`.

### Create or review glossary terms

You can create BigQuery custom glossary terms local to an agent,
or review business glossary terms imported from Knowledge Catalog that
apply to the knowledge sources that you selected for an agent.

- Because business glossary terms from Knowledge Catalog apply globally to BigQuery resources, if you use Knowledge Catalog, [create and manage](https://docs.cloud.google.com/knowledge-catalog/docs/manage-glossaries.md.txt) business glossary terms in Knowledge Catalog instead of for individual agents.
- If you need to modify business glossary terms imported from Knowledge Catalog, you must edit them in Knowledge Catalog and return to BigQuery to see them.
- BigQuery custom glossary terms stay in BigQuery. They don't appear in Knowledge Catalog.
- If you're not using Knowledge Catalog, you can create BigQuery custom glossary terms for terms that you need to define for a specific agent.

Follow these steps to create custom glossary terms for an agent:

1. In the **Glossary** section of the agent **Editor** page, click **Add term**.
2. In the **Custom terms** section, you can edit or delete any existing custom terms.
3. To create one or more new terms, click **Create term** .
   1. Enter a **Term** , a **Definition** , and one or more **Synonyms** separated by a comma.
   2. To create the term, click **Add**.
   3. If you want to delete the new term, click **Delete**.
4. To create more custom terms, repeat these steps.

Follow these steps to view business glossary terms imported from Knowledge Catalog:

1. In the **Glossary** section of the agent **Editor** page, click **Add term**.
2. Navigate to the page section called **Imported from Dataplex**.
3. To modify imported terms in Knowledge Catalog, click **Go to Dataplex glossaries**.
4. After you've modified the terms in Knowledge Catalog, you can return to the agent **Editor** page to view the modified terms.

### Configure settings

In the **Settings** section, you can configure the following optional settings:

1. In the **Model** section, choose which types of models are available to
   users in a conversation with
   the agent. Both Preview and Generally Available models are available by
   default. Models that are in Preview might use the global endpoint.

2. Create [labels](https://docs.cloud.google.com/bigquery/docs/labels-intro.md.txt) to help you 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 **Settings** section, click **Manage labels**.
   2. Click **Add label**.
   3. In the **key** and **value** fields, enter your key-value pair for the label.
   4. If you want to add more labels, click **Add label** again.
   5. To delete a label, click **Delete**.
   6. When you're finished, click **Add**. The new agent page reopens.
3. To write the agent's conversation events to a BigQuery table
   in the agent's project for [monitoring and
   analysis](https://docs.cloud.google.com/bigquery/docs/create-data-agents#analyze-conversation-logs), in the **Conversation logging**
   section, turn on **Enable conversation logging**:

   1. If the conversation logging settings are unavailable when editing an
      existing agent, switch the view selector to **Draft**, and make sure
      that specific BigQuery tables are selected as knowledge
      sources.

   2. Under **Set a destination for the logs to be stored** , select an
      existing destination dataset in the agent's project in **Dataset ID** .
      In **Table ID** , select an existing table, or click **Select or create a
      table** \> **+ New table** , enter a table name under **Specify
      new table** (for example, `agent_events`), and click **Save**.

   3. Review the **Data logging \& user disclosure notice**.

   4. Wait for the settings to be validated. If the dataset doesn't exist,
      create it in BigQuery first. If the Conversational Analytics API
      service agent
      (`service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com`) lacks
      access to the dataset, click **Grant Access** to grant
      `roles/bigquery.dataEditor` on the dataset, or ask your administrator to
      grant it.

   After you publish the agent, ask a test question from the published agent's
   main chat screen (the **Preview** section isn't logged) and refresh the
   destination dataset in BigQuery Studio to confirm that the log
   table appears. To update the destination or turn off logging later, [edit
   the agent](https://docs.cloud.google.com/bigquery/docs/create-data-agents#edit-agent) and publish your changes (existing rows aren't
   deleted). For more information, see [Conversation logging
   overview](https://docs.cloud.google.com/bigquery/docs/conversation-logging-overview).
4. 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. You must set this limit to `10485760` or higher, otherwise you
   receive the following error message:

    Value error. In BigQuery on-demand pricing charges are
    rounded up to the nearest MB, with a minimum of 10 MB of data processed
    per query. So, max bytes billed must be set to greater or equal to
    10485760.

If you don't specify a value, `maximum bytes billed` defaults to the
project's [query usage per day quota](https://docs.cloud.google.com/bigquery/quotas.md.txt#query_jobs). The
usage per day quota is unlimited unless you have specified a [custom
quota](https://docs.cloud.google.com/bigquery/docs/custom-quotas).

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

### Preview and publish the agent

1. In the **Preview** section, type an example user 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. Click **Publish** to open the **Publishing channels** pane and publish
   the data agent, making it available for use in the project.

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** . Immediately after saving
   or publishing your agent, you can see it in the **Agent Catalog**.

You can create conversations with the data agent by using BigQuery Studio or
[Data Studio](https://docs.cloud.google.com/data-studio/conversational-analytics-data-agents.md.txt). You
can also build your own interface to chat with the data agent by using the
Conversational Analytics API. For information on publishing to
Data Studio, see
[Publish a data agent in
Data Studio](https://docs.cloud.google.com/bigquery/docs/create-data-agents#share-agent-data-studio). For information on
publishing to Gemini Enterprise, see [Publish a data agent in
Gemini Enterprise](https://docs.cloud.google.com/bigquery/docs/create-data-agents#publish-agent-gemini-enterprise).

## 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

Follow these steps to edit a data agent:

1. Go to the BigQuery **Agents** page.

   [Go to Agents](https://console.cloud.google.com/bigquery/agents_hub)
2. Select the **Agent Catalog** tab.

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

4. To open the data agent in the agent editor, click

   **Open actions** \> click **Edit** on the agent card.

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

6. To save your changes without publishing, click **Save**.

7. To publish your changes, click **Publish** . In the **Share** dialog, you
   can either [share](https://docs.cloud.google.com/bigquery/docs/create-data-agents.md.txt#share-a-data-agent) the agent with others, or click
   **Cancel**.

8. To return to the **Agents** pane, click **Go back**.

   ![Go back icon to return to the Agents page from the agent editing
   page.](https://docs.cloud.google.com/static/bigquery/images/ca-go-back.png)

### Share a data agent

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

1. Go to the BigQuery **Agents** page.

   [Go to Agents](https://console.cloud.google.com/bigquery/agents_hub)
2. Select the **Agent Catalog** tab.

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

4. To open the data agent in the agent editor, click

   **Open actions** \> click **Edit** on the agent card.

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

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** list.

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

   - Gemini Data Analytics Data Agent User (`roles/geminidataanalytics.dataAgentUser`): gives permission to chat with the data agent.
   - Gemini Data Analytics Data Agent Editor (`roles/geminidataanalytics.dataAgentEditor`): gives permission to edit the data agent.
   - Gemini Data Analytics Data Agent Viewer (`roles/geminidataanalytics.dataAgentViewer`): gives permission to view the data agent.
10. Click **Save**.

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

12. To return to the **Agents** pane, click
    **Go back**.

    ![Go back icon to return to the Agents page from the agent editing
    page.](https://docs.cloud.google.com/static/bigquery/images/ca-go-back.png)

### Delete a data agent

1. Go to the BigQuery **Agents** page.

   [Go to Agents](https://console.cloud.google.com/bigquery/agents_hub)
2. Select the **Agent Catalog** tab.

3. In either the **My agents** or **My draft agents** section of the **Agent Catalog**
   tab, locate the agent card of the data agent that you want to delete.

4. Click
   **Open actions** \> **Delete**.

5. In the **Delete agent?** dialog, click **Delete**.

## Publish a data agent in Data Studio

When you [publish](https://docs.cloud.google.com/bigquery/docs/create-data-agents.md.txt#preview-publish) your agent and [share](https://docs.cloud.google.com/bigquery/docs/create-data-agents.md.txt#share-a-data-agent)
it with Data Studio users, the agent automatically appears for
those users to chat with on the **Chat with your data** page in Data Studio.

### Create and publish your agent to Data Studio

As a data analyst, you can create, edit, and publish an agent to
Data Studio by completing the following steps:

1. [Create](https://docs.cloud.google.com/bigquery/docs/create-data-agents.md.txt#create-a-data-agent) or [edit](https://docs.cloud.google.com/bigquery/docs/create-data-agents.md.txt#edit-agent) your data agent in BigQuery.
2. [Publish](https://docs.cloud.google.com/bigquery/docs/create-data-agents.md.txt#preview-publish) the agent. When you publish the agent, select **Data Studio** as the publishing option.
3. Follow the instructions to [share](https://docs.cloud.google.com/bigquery/docs/create-data-agents.md.txt#share-a-data-agent) the agent, granting the [appropriate Identity and Access Management roles](https://docs.cloud.google.com/bigquery/docs/create-data-agents.md.txt#required-roles) to your Data Studio users.

### Share your agent with Data Studio users

You can share agents with Data Studio users directly by copying a link that opens a [conversation with the agent in Data Studio](https://docs.cloud.google.com/data-studio/conversational-analytics-data-agents.md.txt) or you can send an email to inform the user that they have access to an agent.

To share a direct link to the agent, you can copy the agent's dedicated URL in these ways:

- From the agent catalog: Select **Open actions** \> select **Copy link** \> select **Data Studio**.
- From the agent details view: Select **Copy agent link** \> select **Data Studio**.
- From the **Share** overflow menu: Select **Copy link to agent in Data Studio**.
- After clicking **Save** from the **Share permissions** panel: Select **Copy link**.

To send an email notification that informs recipients of their access to an agent, select **Send email** from the **Share permissions** panel. Email notifications are sent only to the users or groups with whom you have just shared the agent in that editing session. All members of a group receive the email notification, even if a given user already has agent-level permission for the agent. The email includes the name of the user who shared the agent, the name of the agent, and a link to open the agent in Data Studio.

> [!NOTE]
> **Note:** If you're emailing a Google Group that has **Who Can Post** settings set to **Group Members Only** , a Group Owner or Manager must update the group's settings to **Entire Organization** to enable deliveries.

## Publish a data agent in Gemini Enterprise

You can publish a BigQuery data agent in
Gemini Enterprise so that business users can query and analyze
data using natural language directly within Gemini Enterprise.
This process typically involves collaboration between data analysts,
Gemini Enterprise administrators, and business users. For more
information about the roles required for these users, see
[Required roles](https://docs.cloud.google.com/bigquery/docs/create-data-agents.md.txt#required-roles).

To publish a data agent in Gemini Enterprise, complete the
following steps:

1. Review prerequisites.
2. Create and publish the data agent in BigQuery.
3. Provision the agent in Gemini Enterprise.
4. Discover and chat with the agent.

### Review prerequisites

The recommended way to publish BigQuery conversational analytics agents
is by using [Agent Registry](https://docs.cloud.google.com/bigquery/docs/create-data-agents.md.txt#import-from-agent-registry). Follow the
prerequisites in this section to ensure that the agent is discoverable in
Gemini Enterprise.

Alternatively, you can publish the agent by using the [A2A card
JSON](https://docs.cloud.google.com/bigquery/docs/create-data-agents#import-using-a2a-json). If you use this method, see [Create and publish
the data agent in
BigQuery](https://docs.cloud.google.com/bigquery/docs/create-data-agents#publish-agent-bigquery).

To use Agent Registry, you must first configure the
[Agent Gateway](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/agent-gateway-overview.md.txt)
with the appropriate region mapping. The storage region for the
BigQuery data agent and the Agent Gateway
registry binding in Gemini Enterprise must match.

You configure the storage region for the agent in the **Region** section of the
[agent editor](https://docs.cloud.google.com/bigquery/docs/create-data-agents.md.txt#edit-agent) in the BigQuery web UI.
You can't change the region after the agent is saved.

The following image shows the available region options in
Agent Gateway:

![Available region options in Agent Gateway for agent
registries.](https://docs.cloud.google.com/static/bigquery/images/agent-region.png)

As the Gemini Enterprise administrator, configure an
Agent Gateway for your Gemini Enterprise
application by completing the following steps:

1. [Set up an
   Agent Gateway](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/set-up-agent-gateway) that includes the Agent Registry binding matching your data agent's region. Options include **US** , **EU** , or **Global**.
2. In Gemini Enterprise, open your application, go to **Security** \> **Configuration** , and then enter the gateway resource name in the **Agent Gateway configuration** section. For detailed instructions, see [Route Gemini Enterprise traffic through
   Agent Gateway](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/agent-gateway-ge-deploy).

### Create and publish the data agent in BigQuery

As a data analyst, you create, configure, and publish an agent in
BigQuery by completing the following steps:

1. In BigQuery, [create](https://docs.cloud.google.com/bigquery/docs/create-data-agents.md.txt#create-a-data-agent) or [edit](https://docs.cloud.google.com/bigquery/docs/create-data-agents.md.txt#edit-agent) your data agent.
2. In the **Region** section, verify that the storage region matches your data sources and your Agent Gateway configuration. Options include **US** , **EU** , or **Global**.
3. Click **Publish** , or **Publish updates** if the agent was previously published.
4. In the **Publishing channels** pane, under **Additional channels** , choose your publishing method:
   - If your BigQuery and Gemini Enterprise are in the same project, in the **Agent Registry** section, select the **Register this agent** checkbox.
     - If you want to remove the agent from the registry, click **Unregister**.
   - If your BigQuery and Gemini Enterprise are in different projects, in the **Integrate via A2A
     (Agent2Agent)** section, click **Copy JSON** to copy the A2A endpoint JSON data, and then share the JSON data with your Gemini Enterprise administrator. This JSON data is used when you [provision the agent in
     Gemini Enterprise](https://docs.cloud.google.com/bigquery/docs/create-data-agents#provision-agent-gemini-enterprise) section.
5. Click **Publish** or **Publish updates**.
6. [Share](https://docs.cloud.google.com/bigquery/docs/create-data-agents.md.txt#share-a-data-agent) the agent with the users and groups who need access, granting them the Gemini Data Analytics Data Agent User (`roles/geminidataanalytics.dataAgentUser`) role.

### Provision the agent in Gemini Enterprise

As the Gemini Enterprise administrator, make the data agent
available to users in your application using one of the following methods:

#### Option 1: Import from Agent Registry

Follow these steps to import the registered agent:

1. If Gemini Enterprise is in a different project from the BigQuery project, complete the following steps to [manually register the
   agent](https://docs.cloud.google.com/agent-registry/manual-registration#register-remote-agent) in Agent Registry. Otherwise, skip this step:
   1. In the Google Cloud console, go to **Agent Registry** in the same project as Gemini Enterprise, select the **Agents** tab, and then click **Add agent**.
   2. In the **Agent details** pane, for **Type** , select **A2A**.
   3. For **Region**, select the region that matches your data agent and Agent Gateway configuration.
   4. Select **Paste JSON** , paste the A2A endpoint JSON data from BigQuery, and then click **Save**.
2. In Gemini Enterprise, click the name of the app where you want to add the agent.
3. In the navigation menu, click **Agents** \> click **Add agent**.
4. In the **Choose an agent type** pane, locate **Agents from Agent Registry** and click **Add**.
5. In the **Add agent** pane, search for the agent by name, Agent Registry ID, type, producer, or use case, or locate the agent card in the list.
6. On the agent card, click **Add agent**.
7. In the **Review agent details** step, review the agent metadata populated from the agent's A2A card including name, description, agent URL, capabilities, and skills, and then click **Next**.
8. In the **Authenticate agent** step, select how Gemini Enterprise authenticates against the agent provider:
   - **Default Google-managed credentials**: Google manages the OAuth credentials automatically. You don't need to manually configure or enter client credentials.
   - **Custom OAuth**: Select this option only if your organization requires custom OAuth client credentials, and enter the Client ID, Client secret, Authorization URL, and Token URL.
9. Click **Finish**.
10. The agent appears in the **Agents table** with the state **Enabled** and agent type **A2A (Custom)**.
11. [Share the
    agent](https://docs.cloud.google.com/gemini/enterprise/docs/share-custom-agents#share_an_agent) with the users or groups who need access.

#### Option 2: Import using A2A card JSON

> [!WARNING]
>
> **Preview**
>
>
> This feature is
>
> subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the
> [Service Specific
> Terms](https://docs.cloud.google.com/terms/service-terms#1).
>
> Pre-GA features are available "as is" and might have limited support.
>
> For more information, see the
> [launch stage descriptions](https://cloud.google.com/products/#product-launch-stages).

If BigQuery and Gemini Enterprise are in
different projects, follow these steps to import the agent using the A2A card
JSON:

1. In Gemini Enterprise, click the name of the app where you want to add the agent.
2. In the navigation menu, click **Agents** \> click **Add agent**.
3. In the **Choose an agent type** pane, locate **Custom agent via A2A** and click **Add**.
4. In the **Agent card JSON** field, enter the agent card JSON received from the data analyst.
5. Click **Preview agent details** \> click **Next**.
6. In the **Agent authorization** step, select your authentication method:
   - **Default Google-managed credentials**: Google manages the OAuth credentials automatically without requiring you to manually enter or generate a client ID and client secret.
   - **Custom OAuth** : Select this option if you want to manually provide custom OAuth credentials, following the steps in [Register and manage A2A
     agents](https://docs.cloud.google.com/gemini/enterprise/docs/register-and-manage-an-a2a-agent#authorize-your-agent).
7. In the **Tool authorizations** step, click **Finish**.
8. The agent appears in the **Agents table** with the state **Enabled** and agent type **A2A (Custom)**.
9. [Share the
   agent](https://docs.cloud.google.com/gemini/enterprise/docs/share-custom-agents#share_an_agent) with the users or groups who need access.

### Discover and use an agent

You can discover and use a data agent in Gemini Enterprise using
any of these methods:

- **Manual discovery** : Locate a data agent in the [Agent Gallery](https://docs.cloud.google.com/gemini/enterprise/docs/agent-gallery.md.txt) and use it with any of these methods:
  - **Browse the gallery**: Select the agent and start a dedicated chat.
  - **Direct link**: Use the agent's dedicated URL to open Gemini Enterprise directly into a session with that specific BigQuery data agent.
  - **Directed intent** : Invoke the agent by `@mention` (for example, `@sales_pipeline_agent`) in the Gemini Enterprise core chat.
  - **Seamless orchestration**: Ask a general analytical question (for example, "How is our sales pipeline trending in the last 3 months?") and Gemini Enterprise automatically routes the query to the relevant data agent.

After you've discovered the agent, you can interact with it by performing the
following steps:

- **Authenticate**: Complete the one-time OAuth sign-in to securely authenticate to BigQuery.
- **Chat**: Ask natural language questions to the agent. The requests are processed by the agent, and the response is streamed back to Gemini Enterprise as text, Markdown, charts, or tables.
- **View conversation history**: Conversations are automatically saved in the history pane.

## Monitor agents and conversations

You can monitor the performance, adoption, latency, and costs of your data
agents and their conversations by using Google Cloud Observability in BigQuery.
When you enable agent observability, you can view metrics such as the following:

- The number of agents used in conversations
- The number of users who have asked questions
- The number of conversations created
- The agents that have answered the most questions
- The most commonly used knowledge sources
- User engagement
- Projected token usage
- Hourly answer latency

### Before you begin


Enable the Cloud Trace, Cloud Monitoring,
Cloud Logging APIs, if any are not already enabled.


**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](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).

[Enable the APIs](https://console.cloud.google.com/apis/enableflow?apiid=cloudtrace.googleapis.com,monitoring.googleapis.com,logging.googleapis.com)

#### Required roles and permissions

To enable agent observability, you must have the following permissions on your
project:

- `cloudaicompanion.gibqObservabilitySettings.create`
- `cloudaicompanion.gibqObservabilitySettings.list`
- `cloudaicompanion.gibqObservabilitySettings.update`
- `cloudaicompanion.settingBindings.gibqObservabilitySettingsCreate`
- `cloudaicompanion.settingBindings.gibqObservabilitySettingsList`
- `cloudaicompanion.settingBindings.gibqObservabilitySettingsUse`
- `geminidataanalytics.dataAgents.create`
- `geminidataanalytics.operations.get`
- `observability.traceScopes.create`
- `resourcemanager.projects.update`
- `serviceusage.services.enable`
- `serviceusage.values.test`


To get the permissions that
you need to monitor your agents by using metrics, traces, and logs,

ask your administrator to grant you the
following IAM roles on your project:

- View monitoring data and configurations: [Monitoring Viewer](https://docs.cloud.google.com/iam/docs/roles-permissions/monitoring.md.txt#monitoring.viewer) (`roles/monitoring.viewer`)
- View traces: [Cloud Trace User](https://docs.cloud.google.com/iam/docs/roles-permissions/cloudtrace.md.txt#cloudtrace.user) (`roles/cloudtrace.user`)
- View logs: [Logs Viewer](https://docs.cloud.google.com/iam/docs/roles-permissions/logging.md.txt#logging.viewer) (`roles/logging.viewer`)
- View datasets and their contents: [BigQuery Data Viewer](https://docs.cloud.google.com/iam/docs/roles-permissions/bigquery.md.txt#bigquery.dataViewer) (`roles/bigquery.dataViewer`)
- View administrator settings: [Gemini for Google Cloud User](https://docs.cloud.google.com/iam/docs/roles-permissions/cloudaicompanion.md.txt#cloudaicompanion.user) (`roles/cloudaicompanion.user`)


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

### Enable observability

Agent observability is disabled by default. An administrator can enable it for
your project or organization. To enable observability for your agents,
select one of the following options:

### Console

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

   [Go to Agents](https://console.cloud.google.com/bigquery/agents_hub)
2. Select the **Monitoring** tab.

3. If observability is disabled, follow the prompts to enable it.

### Google Cloud CLI

1. Create an observability setting:

   ```bash
   gcloud gemini gibq-observability-settings create SETTING_NAME \
     --conversational-analytics-setting-metrics-enabled \
     --conversational-analytics-setting-traces-enabled \
     --project=PROJECT_ID \
     --location=global
   ```

   Replace the following:
   - `SETTING_NAME`: A name for the observability setting.
   - `PROJECT_ID`: Your project ID.
2. Bind the observability setting to your project:

   ```bash
   gcloud gemini gibq-observability-settings setting-bindings create BINDING_NAME \
     --gibq-observability-setting=SETTING_NAME \
     --target=projects/PROJECT_ID \
     --location=global \
     --project=PROJECT_ID
   ```

   Replace `BINDING_NAME` with a name for the setting
   binding. We recommend that you use
   `binding-PROJECT_ID` for your binding name.

### API

1. Create an observability setting:

   ```bash
   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       -d '{
             "conversational_analytics_setting": {
               "metrics_enabled": true,
               "traces_enabled": true
             }
           }' \
       "https://cloudaicompanion.googleapis.com/v1/projects/PROJECT_ID/locations/global/gibqObservabilitySettings?gibq_observability_setting_id=SETTING_NAME"
   ```

   Replace the following:
   - `SETTING_NAME`: A name for the observability setting.
   - `PROJECT_ID`: Your project ID.
2. Bind the observability setting to your project:

   ```bash
   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       -d '{
             "target": "projects/PROJECT_ID",
             "product": "GEMINI_IN_BIGQUERY"
           }' \
       "https://cloudaicompanion.googleapis.com/v1/projects/PROJECT_ID/locations/global/gibqObservabilitySettings/SETTING_NAME/settingBindings?setting_binding_id=BINDING_NAME"
   ```

   Replace `BINDING_NAME` with a name for the setting
   binding. We recommend that you use
   `binding-PROJECT_ID` for your binding name.

### View metrics

Metrics are collected after you enable observability. Data
isn't backfilled.
To view agent metrics, select one of the following options:

### BigQuery

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

   [Go to Agents](https://console.cloud.google.com/bigquery/agents_hub)
2. Select the **Monitoring** tab.

### Cloud Monitoring

1. In the Google Cloud console, go to the Cloud Monitoring **Dashboards**
   page.

   [Go to Dashboards](https://console.cloud.google.com/monitoring/dashboards)
2. In the **My Dashboards** pane, search for the dashboard named
   `BigQuery Conversational Analytics`.

3. To open the dashboard, click its name.

4. Optional: Create a [custom dashboard](https://docs.cloud.google.com/monitoring/charts/dashboards.md.txt).

5. Optional: To view metrics individually, go to the **Metrics explorer**
   page.

   [Go to Metrics explorer](https://console.cloud.google.com/monitoring/metrics-explorer)

   Agent metrics include agent usage, model calls, tool usage, health,
   latency, and token usage.

### Debug model calls

You can visualize the sequence of operations within a conversation turn,
such as model calls and tool calls, to help you troubleshoot errors and latency.

1. In the Google Cloud console, go to the Cloud Monitoring
   **Trace explorer** page.

   [Go to Trace explorer](https://console.cloud.google.com/traces/explorer)
2. Click a span to examine.

3. Review the information in the **Details** pane.

4. Optional: Create a
   [custom trace dashboard](https://docs.cloud.google.com/trace/docs/display-traces-on-dashboards.md.txt).

### Retain traces

Your Cloud Trace data is stored in an observability dataset for 30 days. To
store your trace data for longer, move your trace data to
a BigQuery dataset.

#### Required roles


To get the permissions that
you need to expose live traces to BigQuery by creating
a linked dataset,

ask your administrator to grant you the
following IAM roles on your project:

- [Cloud Trace Admin](https://docs.cloud.google.com/iam/docs/roles-permissions/cloudtrace.md.txt#cloudtrace.admin) (`roles/cloudtrace.admin`)
- [Observability Editor](https://docs.cloud.google.com/iam/docs/roles-permissions/observability.md.txt#observability.editor) (`roles/observability.editor`)
- [BigQuery User](https://docs.cloud.google.com/iam/docs/roles-permissions/bigquery.md.txt#bigquery.user) (`roles/bigquery.user`)


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

#### Move trace data to BigQuery

To retain your trace data, do the following:

1. Open [Cloud Shell](https://console.cloud.google.com/bigquery?cloudshell=true).

2. Find the location of your `_Trace` bucket:

   ```bash
   gcloud observability buckets list --location=-
   ```

   Note the location of your `_Trace` bucket for the next step.
3. Create a
   [linked dataset](https://docs.cloud.google.com/bigquery/docs/analytics-hub-introduction.md.txt#linked_datasets)
   in your BigQuery project that points to your `_Trace` bucket:

   ```bash
   gcloud observability buckets datasets links create \
       projects/PROJECT_ID/locations/LOCATION/buckets/_Trace/datasets/Spans/links/LINK_NAME \
       --dataset=Spans \
       --bucket=_Trace \
       --location=LOCATION \
       --project=PROJECT_ID
   ```

   Replace the following:
   - `PROJECT_ID`: your project ID
   - `LOCATION`: the location of your `_Trace` bucket from the previous step
   - `LINK_NAME`: a name for the linked dataset
4. Create a [standard dataset](https://docs.cloud.google.com/bigquery/docs/datasets.md.txt#create-dataset)
   in which to store your historical traces.
   The following command sets the
   [default partition expiration](https://docs.cloud.google.com/bigquery/docs/managing-partitioned-tables.md.txt#partition-expiration)
   to 90 days (7,776,000 seconds):

   ```bash
   bq --location=LOCATION mk \
       --dataset \
       --default_partition_expiration=7776000 \
       --description="Archive storage for historical traces" \
       PROJECT_ID:STORAGE_DATASET
   ```

   Replace `STORAGE_DATASET` with a name for the
   dataset.
5. Create an empty partitioned table in your
   storage dataset with the same schema as the linked dataset. Partitioning by
   date helps you manage data retention and query costs. To create the table,
   run the following query in the SQL editor:

   ```sql
   CREATE TABLE `PROJECT_ID.STORAGE_DATASET.TABLE_NAME`
   PARTITION BY DATE(start_time)
   AS
   SELECT *
   FROM `PROJECT_ID.LINK_NAME._AllSpans`
   WHERE FALSE;
   ```

   Replace `TABLE_NAME` with a name for the
   table.
6. Create a [scheduled query](https://docs.cloud.google.com/bigquery/docs/scheduling-queries.md.txt) to copy daily
   trace data from the linked dataset to your archive table. The following
   query copies data from the previous day:

   ```sql
   INSERT INTO `PROJECT_ID.STORAGE_DATASET.TABLE_NAME`
   SELECT *
   FROM `PROJECT_ID.LINK_NAME._AllSpans`
   WHERE start_time >=
     TIMESTAMP_SUB(TIMESTAMP_TRUNC(CURRENT_TIMESTAMP(), DAY), INTERVAL 1 DAY)
     AND start_time < TIMESTAMP_TRUNC(CURRENT_TIMESTAMP(), DAY);
   ```

For more information, read about how to
[find and explore traces](https://docs.cloud.google.com/trace/docs/finding-traces.md.txt).

### Turn off observability

To turn off observability for your data agents, update your observability
setting:

```bash
gcloud gemini gibq-observability-settings update SETTING_NAME \
    --no-conversational-analytics-setting-metrics-enabled \
    --no-conversational-analytics-setting-traces-enabled \
    --project=PROJECT_ID \
    --location=global
```

Replace the following:

- `SETTING_NAME`: The name of the observability setting that you created to enable observability. If you enabled observability by using the Google Cloud console, then the setting name is `default`.
- `PROJECT_ID`: Your project ID.

## Analyze conversation logs in BigQuery

In addition to project-level observability metrics in Cloud Monitoring and
spans in Cloud Trace, you can enable per-agent [conversation
logging](https://docs.cloud.google.com/bigquery/docs/create-data-agents#configure_settings) in BigQuery Studio to write each
conversation turn---including the user's question, the agent's answer, latency,
and model token usage---to a BigQuery table in your agent's
project. You can then query and evaluate the logged events using
GoogleSQL, interactive Colab notebooks, or the
[BigQuery agent
analytics](https://docs.cloud.google.com/bigquery/docs/bigquery-agent-analytics) Python SDK. For more
information, see [Conversation logging
overview](https://docs.cloud.google.com/bigquery/docs/conversation-logging-overview).

## What's next

- Learn more about [conversational analytics in
  BigQuery](https://docs.cloud.google.com/bigquery/docs/conversational-analytics).
- Learn more about the [Conversational Analytics API](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/overview.md.txt).
- [Analyze data with conversations](https://docs.cloud.google.com/bigquery/docs/create-conversations.md.txt).
- Learn more about how the [Gemini Data Analytics Data Agent Viewer
  (`roles/geminidataanalytics.dataAgentViewer`)](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/access-control#data-agent-viewer) role gives permission to view the data agent.