<br />

<br />

Data agents let you curate the [Conversational Analytics](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-overview) experience for your users. With agents, you can provide Conversational Analytics with context and instructions to enable it to answer questions more effectively for specific use cases. Agents empower analysts to map business terms to specific fields, specify the best fields for filtering, and define custom calculations.

This page guides you through the following processes:

- [Create and edit data agents](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data-agents#create-and-edit-data-agents)
- [Share data agents with other users](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data-agents#share-data-agents)
- [Delete data agents](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data-agents#delete-a-data-agent)

Learn [how and when Gemini
for Google Cloud uses your data](https://docs.cloud.google.com/gemini/docs/discover/data-governance).

## Before you begin

The use of Conversational Analytics is managed through a combination of [content access, data access, and feature access](https://docs.cloud.google.com/looker/docs/2606/access-control-and-permission-management). Think of a data agent as another type of Looker content --- like a dashboard, Look, or folder. To interact with data agents, you must be assigned a Looker role that has the required permissions for the models that underlie the individual Explore or that the data agent will query. In some cases, you will also need access to the agent itself. For more information about the permissions and access that are required to manage and user data agents, see the permissions table on the [Set up Conversational Analytics in Looker](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-setup#required-permissions) documentation page.

## Create and edit data agents

> [!CAUTION]
> As an early-stage technology, Gemini for Google Cloud
> products can generate output that seems plausible but is factually incorrect. We recommend that you
> validate all output from Gemini for Google Cloud products before you use it.
> For more information, see
> [Gemini for Google Cloud and responsible AI](https://docs.cloud.google.com/gemini/docs/discover/responsible-ai).

To create a new data agent, follow these steps:

1. Navigate to the [**Conversations** page](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data#navigate-to-conversational-analytics).
2. In the **Agents** tab, select **+ New agent** . Or, in the left panel, select spark**Manage agents** , and then select **+ New agent**.
3. On the **New agent** page, provide the following information about your data agent.

   - **Agent name**: Enter a name for the agent. The name should be unique and descriptive.
   - **Agent description** : Briefly describe what this agent can do and the data that it uses. Users will see this description when they select the agent to [start a conversation](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data#start-a-conversation-with-an-agent) or when you share the agent with them, so make sure that the description clearly explains the agent's purpose and how it can be helpful.
   - **Data** : Follow these steps to connect to up to five existing Looker Explores:
     1. In the **Data** field, click **+ Select Explores**.
     2. In the **Search Explores** window, click the Explores that you want to include in the data agent. These Explores will appear in the **Selected Explores** panel of the window.
     3. To add the selected Explore to the data agent, click **Save**.
4. **Instructions** : Provide context to help Conversational Analytics understand how to interact with your data and provide accurate and relevant responses. For examples of the types of context that you can provide, see [Writing agent instructions](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data-agents#write-agent-instructions).

5. Optionally, to enable the [Code Interpreter](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-code-interpreter) for all conversations with your agent, select **Enable Advanced Analytics**.

6. Optionally, you can [test your agent](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data-agents#test-an-agent) to refine your instructions and its settings.

7. To save your new data agent, click **Save**.

After you save the data agent, you can [share the agent](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data-agents#share-data-agents) with other users and [start a conversation](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data#start-a-conversation-with-an-agent) with the agent.

### Write agent instructions

When you create a data agent, you can add free-form instructions that define your data agent's core behavior and provide it with foundational context to consider before processing a user's prompt.

> [!IMPORTANT]
> **Important:** Although the **Instructions** field is optional and the structure is up to your discretion, we recommend that you provide well-structured instructions to enable the agent to give more accurate and relevant responses.

Here are some examples of the types of context that you can provide in the **Instructions** field:

- Key fields: The most important fields for analysis
- Excluded fields: Fields that the data agent should avoid
- Filtering and grouping: Fields that the agent should use to filter and group data
- Golden queries: Pairs of natural language questions and their corresponding Explore queries
- Persona: A role or expertise, character, or tone that you assign to the agent

> [!NOTE]
> **Note:** The types of authored context that you can provide a data agent in Looker differ slightly from those that you can provide an agent that you are creating using the Conversational Analytics API. Some of what you provide in the **Instructions** field in Looker --- such as golden queries --- can be given to an agent as [structured context](https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/data-agent-authored-context-looker#structured-context-looker) using the Conversational Analytics API.

For tips and best practices for writing agent instructions, see the [Best practices for configuring Conversational Analytics in Looker](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-best-practices).

#### Define a Looker golden query

To define each Looker golden query for a given Explore, provide values for both of
the following fields:

- `natural_language_questions`: The natural language question that a user might ask
- `looker_query`: The Looker golden query that corresponds to the natural language question

> [!TIP]
> **Tips for defining Looker golden queries:**
>
> <br />
>
> Include different types of questions and queries that have a variety of filters and filter values.
>
> <br />
>
> Although there is no limit to the number of golden queries that you can include to `looker_golden_queries`, we recommend including no more than 30-50 question-and-query pairs.

For the `natural_language_questions` field, consider the questions a user might ask
about that Explore, and write those questions in natural language. You can
include more than one question in this field's value. You can obtain the value
for the `looker_query` field from the Explore's query metadata.

Golden queries support the following fields:

- `model` (string): The LookML model that was used to generate the query. This is a required field.
- `explore` (string): The Explore that was used to generate the query. This is a required field.
- `fields[]` (string): The fields to retrieve from the Explore, including dimensions and measures. This is an optional field.
- `filters[]` (string): The filters to apply to the Explore. This is an optional field.
- `sorts[]` (string): The sorting to apply to the Explore. This is an optional field.
- `limit` (string): The data row limit to apply to the Explore. This is an optional field.

> [!NOTE]
> **Note:** Conversational Analytics doesn't support golden queries that contain `pivots` or custom fields.

You can retrieve the Explore's query metadata directly from the Explore by following these steps:

1. In the Explore, select the [**Explore actions**
   menu](https://docs.cloud.google.com/looker/docs/2606/viewing-and-interacting-with-explores#the_explore_page), and then select **Get LookML**.
2. Select the **Dashboard** tab.
3. Copy the query details from the LookML. For example, the following image shows the LookML for an Explore called **Order Items**:

![](https://docs.cloud.google.com/static/gemini/docs/conversational-analytics-api/images/ca-query-details-explore-260.png)

Copy the selected metadata for use in your Looker golden query:

      model: thelook
      explore: order_items
      fields: [order_items.order_id, orders.status]
      sorts: [orders.status, order_items.order_id]
      limit: 500

### Test an agent

When you're creating or editing an agent, the agent details page includes the **Preview your agent** pane. You can test agent settings and instructions by [starting a conversation](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data#start-a-conversation-with-an-agent) with the agent.

You must click **Update** for a change to be reflected in the preview. If the save status is `Not saved`, any updates to settings won't be reflected in the preview.

### Edit an existing data agent

To edit an existing data agent, follow these steps:

1. On the [**Conversations** page](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data#navigate-to-conversational-analytics), select spark**Manage agents**.
2. On the **Manage agents** page, select the data agent that you want to edit.
3. Update the details about the agent as needed. You can modify the details that you specified when you [created the agent](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data-agents#creating-a-new-data-agent), including the **Agent name** , **Agent description** , **Data** , and **Instructions** fields. You can also opt to enable the [Code Interpreter](https://docs.cloud.google.com/looker/docs/2606/studio/conversational-analytics-looker-code-interpreter) for your agent.
4. To save your changes, click **Update**.

## Share data agents

Sharing lets other users chat with your agent and its Explores. You can share a data agent with other users by granting content access to the agent. Only a user with the [appropriate permissions and content access](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data-agents#before-you-begin) can share an agent. Once an agent is created, it may take a few minutes for it to become shareable.

> [!NOTE]
> **Note:** Granting a user content access to an agent does *not* also grant that user access to the Explore that the agent uses. When you share an agent, make sure that the users also have the permissions that they need to use Conversational Analytics with the model that the Explore is based on. Your Looker admin may need to grant these permissions.

To share a data agent, follow these steps:

1. On the [**Conversations** page](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data#navigate-to-conversational-analytics), select spark**Manage agents** in the left panel.
2. Open the menu for the chosen agent by clicking its **More options** icon, and then click **Share**.
3. Once you have added an individual or groups to the **Who can access this agent** section, and chosen what level of permissions they should have, click **Add** to place them in the shared list.
4. If you want new users or groups to receive a notification email, select the **Email the people you have just added** checkbox.
5. After all changes have been made, click **Save**.

You can also share an agent that you've just created or one that you're editing by clicking **Share** on the agent settings page and following the aforementioned steps.

### Revoke access to a data agent

To revoke access to an agent, follow these steps:

1. On the [**Conversations** page](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data#navigate-to-conversational-analytics), click spark**Manage agents** in the left panel.
2. Open the menu for the chosen agent by clicking its **More options** icon, and then click **Share**.
3. Click the **X** next to the user or groups that should have their access removed.
4. After all changes have been made, click **Save**.

If the removed users have an ongoing conversation, they will still have access for a minute or two while the changes propagate.

If a user tries to ask more questions once access to an agent is removed, then that user will see the message `The agent in this conversation may not be shared with you, or may have been deleted. You can view any past conversations with the agent, but can't ask new questions.`

## Delete a data agent

> [!CAUTION]
> **Caution:** Any users with whom you have shared this data agent won't be able to ask new questions after you delete the agent; however, existing conversations with the data agent are retained.
>
> <br />
>
> If you delete an agent, you will also delete and [unpublish the agent in Gemini Enterprise](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data-agents#publish-data-agents).

To delete a data agent, follow these steps:

1.On the [**Conversations** page](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data#navigate-to-conversational-analytics), click spark**Manage agents** in the left panel.
1. Open the menu for the chosen agent by clicking its **More options** icon, and then click **Delete** .
1. In the **Delete agent?** window, click **Move to trash** to delete the data agent.

Agents that are moved to the trash will be permanently deleted after 30 days. You can [permanently delete a data agent](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data-agents#permanently-delete-a-data-agent) manually, or you can [restore a data agent from the trash](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data-agents#restore-a-data-agent-from-the-trash) before it is permanently deleted. If you take no action, the agent will be deleted permanently after 30 days automatically.

### Permanently delete a data agent

To permanently delete a data agent, follow these steps:

1. Navigate to the [**Conversations** page](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data#navigate-to-conversational-analytics).
2. In the left navigation panel, expand the **Trash** section.
3. To open the menu for the chosen agent, select its icon, and then click **Delete Permanently**.
4. In the **Are you sure?** window, click **Delete forever**.

### Restore a data agent from the trash

To restore a data agent from the trash, follow these steps:

1. Navigate to [**Conversations** page](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-data#navigate-to-conversational-analytics).
2. In the left navigation panel, expand the **Trash** section.
3. To open the menu for the chosen agent, select its icon, and then click **Restore**.

## Related resources

- **[Conversational Analytics in Looker overview](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-overview)**: The landing page for Conversational Analytics with a list of key features links to all Conversational Analytics documentation.

- **[Best practices for configuring Conversational Analytics in Looker](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-best-practices)**: Strategies and best practices to help Looker administrators and LookML developers successfully configure optimize Conversational Analytics.

- **[Enable advanced analytics with the Code Interpreter](https://docs.cloud.google.com/looker/docs/2606/conversational-analytics-looker-code-interpreter)**: The Code Interpreter within Conversational Analytics translates your natural language questions into Python code and executes that code. Compared to standard SQL-based queries, the Code Interpreter's use of Python enables more complex analysis and visualizations.