Create and manage LookML dashboard data agents

Conversational Analytics, powered by Gemini for Google Cloud, lets you investigate your data by asking questions in conversational language through an intuitive chat interface. When you use Conversational Analytics with a LookML dashboard, you can define and customize a dashboard data agent directly in your version-controlled LookML code.

LookML dashboard agents let developers inject tailored business logic, custom instructions, and analytical settings into LookML-managed dashboards. Because LookML dashboards represent governed, version-controlled sources of truth across organizations, LookML dashboard agents ensure that AI interactions remain consistent across environments and adhere to organizational data standards.

This page covers the following topics:

Before you begin

Before you can configure or use LookML dashboard agents, ensure that the following requirements are met:

  • Instance requirements: A Looker admin must enable Conversational Analytics on the Gemini in Looker admin page. The admin must also turn on the Enable Trusted Tester Features and the Enabled Dashboard Agents settings. Advanced Analytics for dashboard agents, the Advanced Analytics admin setting must also be enabled. This setting doesn't apply to LookML dashboard agents in Looker 26.14.
  • Permissions for developers: To create, edit, or configure LookML dashboard agents and dashboards, you must have a Looker role with the develop and see_lookml_dashboards permissions, as well as access to the LookML models that underlie the dashboard.
  • Permissions for viewers: To chat with a LookML dashboard agent, users must have the see_lookml_dashboards permission and access to the LookML models that underlie the dashboard tiles.

Define a dashboard agent in LookML

To define a dashboard agent in LookML, declare the agent parameter in a LookML model file or a dedicated LookML file within your project.

A LookML dashboard agent definition uses the following syntax:

agent: agent_name {
  advanced_analytics: yes | no
  description: "Description of the agent"
  instructions: "Custom agent prompt and instructions"
  is_dashboard_agent: yes
  show_debuginfo: yes | no
  show_thinking: yes | no
}

Dashboard agents support the following LookML parameters:

  • agent: Declares a new agent and defines its name.
  • advanced_analytics: (Optional) Accepts yes or no (default is no). When set to yes, the agent can use Advanced Analytics to translate natural language questions into Python code and execute that code for advanced computations and visualizations. This parameter is available for LookML dashboard agents; however, it is not functional in Looker 26.14.
  • description: (Optional) A brief description of the agent.
  • instructions: (Optional) A string that provides free-form instructions and business context to guide the agent when answering queries. If omitted, the agent uses default conversational processing without custom prompt context.
  • is_dashboard_agent: (Required for dashboard agents) Set to yes to identify the agent specifically as a dashboard agent.
  • show_debuginfo: (Optional) Accepts yes or no (default is no). When set to yes, the agent displays detailed execution and troubleshooting information in conversation responses.
  • show_thinking: (Optional) Accepts yes or no (default is no). When set to yes, the agent displays its step-by-step reasoning process in conversation responses.

Example dashboard agent definition

The following example defines a LookML dashboard agent that enforces specific filtering rules and tone:

agent: sales_dashboard_agent {
  instructions: "Focus on revenue metrics. Always filter by the current fiscal year unless the user specifies otherwise."
  description: "LookML Dashboard Agent for sales performance analytics."
  is_dashboard_agent: yes
  advanced_analytics: yes
  show_thinking: yes
  show_debuginfo: no
}

Use LookML constants in agent instructions

If you manage multiple LookML dashboards across an organization, you can use LookML constants to share standard business rules, glossaries, or filtering requirements across agent definitions without duplicating text.

To use a constant in agent instructions, follow these steps:

  1. Define the constant in your project's manifest.lkml file:

    constant: FISCAL_YEAR_RULE {
  value: "Always filter all requests by the current fiscal year unless the user explicitly specifies a different timeframe."
}

  2. Reference the constant in the instructions parameter of your dashboard agent using @{<var>CONSTANT_NAME</var>} syntax:

    agent: finance_dashboard_agent {
  instructions: "Prioritize gross margin and operating expense metrics. @{FISCAL_YEAR_RULE}"
  is_dashboard_agent: yes
  advanced_analytics: yes
}

When the agent processes queries, Looker dynamically substitutes the constant string into the agent instructions.

Associate a dashboard agent with a LookML dashboard

To attach a dashboard agent to a LookML dashboard, configure the dashboard-level parameters in the .dashboard.lookml file.

The following dashboard parameters control agent behavior on LookML dashboards:

  • enable_dashboard_agent: (Optional) Accepts true or false. Determines whether users can see the spark Chat with this dashboard icon and interact with the dashboard agent. If omitted, this parameter defaults to true at the API layer.
  • default_dashboard_agent: (Optional) Specifies the name of the LookML agent (defined with the agent parameter) that serves as the default agent for the dashboard.
  • dashboard_agents: (Optional) A list of agent names available for the dashboard.

Example LookML dashboard configuration

The following snippet shows how to map the sales_dashboard_agent to a LookML dashboard:

- dashboard: executive_sales_overview
  title: "Executive Sales Overview"
  layout: newspaper
  enable_dashboard_agent: true
  default_dashboard_agent: sales_dashboard_agent
  dashboard_agents: [sales_dashboard_agent, regional_sales_agent]

  elements:
  - name: total_revenue_by_quarter
    type: looker_column
    model: sales_ops
    explore: orders
    measures: [orders.total_revenue]
    dimensions: [orders.created_quarter]

If enable_dashboard_agent is set to true and no default_dashboard_agent is specified, users can still chat with the dashboard; the agent will run without custom instructions.

Test LookML dashboard agents in Development Mode

LookML developers can iteratively modify agent instructions and test responses directly in the Looker UI before deploying changes to production.

To test a LookML dashboard agent in Development Mode:

  1. Turn on Development Mode.
  2. Edit the agent instructions or settings in your LookML file and save your changes.
  3. Open the LookML dashboard in the Looker UI.
  4. Select spark Chat with this dashboard to open the chat panel.
  5. Ask questions to test how the agent interprets and responds to your prompts.

When Development Mode is turned on, Conversational Analytics references the in-memory agent definition, LookML dashboard definition, and model files from your development branch. When you turn Development Mode off, Conversational Analytics reverts to referencing the deployed definitions from the production branch.

Conversation history created during Development Mode is persisted and visible in your recent conversations list across sessions.

Copy dashboard agent LookML from user-defined dashboards

If you prototype a dashboard as a user-defined dashboard in the UI, you can export its complete configuration—including the dashboard agent settings and instructions—into LookML code.

To copy LookML from a user-defined dashboard:

  1. Open the user-defined dashboard.
  2. Select the three-dot more_vert Dashboard actions menu, and then select Get LookML.
  3. In the Get LookML dialog, copy the generated dashboard LookML and the dashboard agent definition code.
  4. Paste the dashboard LookML into a .dashboard.lookml file, and paste the agent block into your model or agent LookML file.

The exported LookML preserves the state of the Enable chat with dashboard toggle by using the enable_dashboard_agent parameter and copies any custom agent instructions.

View agent details in the Looker UI

When viewing a LookML dashboard with an active dashboard agent, you can inspect the agent configuration from the chat panel:

  1. Select spark Chat with this dashboard.
  2. Select tune Manage agent.

For LookML dashboards, the Manage agent panel displays agent instructions, Advanced Analytics status, and debug options in read-only mode. Settings cannot be edited directly within the UI.

To edit the configuration, developers with the develop permission on the underlying models can click Edit in LookML to navigate directly to the relevant LookML file in the IDE.

Query a LookML dashboard with a dashboard agent

To start a conversation with a LookML dashboard agent:

  1. Open the LookML dashboard.
  2. Select spark Chat with this dashboard.
  3. In the Ask a question field, enter your query in natural language.
  4. If show_thinking is allowed for your dashboard agent, you can choose a question mode:
    • Fast: Quickly translates your query into direct LookML metric lookups.
    • Thinking: Evaluates complex analytical questions and displays step-by-step reasoning.
  5. Click send Send.

To cancel a query in progress, click Stop response.

Manage conversations

  • Recent conversations: To open previous conversations, select more_vert Menu > Recent conversations.
  • Rename a conversation: Select more_vert next to a conversation and select edit Rename.
  • Delete a conversation: Select more_vert next to a conversation and select delete Delete.