Criar e gerenciar agentes de dados para painéis do LookML

Com a Análise Conversacional, que usa o Gemini para Google Cloud, você pode investigar seus dados fazendo perguntas em linguagem natural em uma interface de chat intuitiva. Ao usar a Análise Conversacional com um painel do LookML, você pode definir e personalizar um agente de dados diretamente no código do LookML com controle de versão.

Com os agentes de dados para dashboards do LookML, os desenvolvedores podem inserir lógica de negócios personalizada, instruções personalizadas e configurações analíticas em dashboards gerenciados pelo LookML. Como os painéis do LookML representam fontes de verdade governadas e com controle de versão em todas as organizações, os agentes de painel do LookML garantem que as interações de IA permaneçam consistentes em todos os ambientes e sigam os padrões de dados organizacionais.

Nesta página, abordamos os seguintes tópicos:

Antes de começar

Antes de configurar ou usar agentes de painel do LookML, verifique se os seguintes requisitos foram atendidos:

  • Requisitos da instância: um administrador do Looker precisa ativar a Análise Conversacional na página de administrador do Gemini no Looker. O administrador também precisa ativar as configurações Ativar recursos de trusted testers e Agentes de painel ativados. Análises avançadas Para agentes de painel, a configuração de administrador Análises avançadas também precisa estar ativada. Essa configuração não se aplica aos agentes de dashboard do LookML no Looker 26.14.
  • Permissões para desenvolvedores: para criar, editar ou configurar agentes e painéis do LookML, você precisa ter uma função do Looker com as permissões develop e see_lookml_dashboards, além de acesso aos modelos do LookML que embasam o painel.
  • Permissões para leitores: para conversar com um agente do painel do LookML, os usuários precisam ter a permissão see_lookml_dashboards e acesso aos modelos do LookML que estão por trás dos blocos do painel.

Definir um agente de dashboard em LookML

Para definir um agente de dashboard no LookML, declare o parâmetro agent em um arquivo de modelo do LookML ou em um arquivo dedicado do LookML no seu projeto.

Uma definição de agente de dashboard do LookML usa a seguinte sintaxe:

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
}

Os agentes do painel são compatíveis com os seguintes parâmetros do LookML:

  • agent: declara um novo agente e define o nome dele.
  • advanced_analytics: (opcional) aceita yes ou no (o padrão é no). Quando definido como yes, o agente pode usar a Análise avançada para traduzir perguntas em linguagem natural para código Python e executar esse código para cálculos e visualizações avançados. Esse parâmetro está disponível para agentes de dashboard do LookML, mas não funciona no Looker 26.14.
  • description: (opcional) uma breve descrição do agente.
  • instructions: (opcional) uma string que fornece instruções de formato livre e contexto comercial para orientar o agente ao responder a consultas. Se omitido, o agente usará o processamento de conversa padrão sem contexto de comando personalizado.
  • is_dashboard_agent: (obrigatório para agentes de painel) definido como yes para identificar o agente especificamente como um agente de painel.
  • show_debuginfo: (opcional) aceita yes ou no (o padrão é no). Quando definido como yes, o agente mostra informações detalhadas de execução e solução de problemas nas respostas da conversa.
  • show_thinking: (opcional) aceita yes ou no (o padrão é no). Quando definido como yes, o agente mostra o processo de raciocínio detalhado nas respostas da conversa.

Os agentes nos painéis do LookML não são compatíveis com consultas verificadas.

Exemplo de definição de agente de painel

O exemplo a seguir define um agente de painel do LookML que aplica regras de filtragem e tom específicos:

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
}

Usar constantes do LookML nas instruções do agente

Se você gerencia vários painéis do LookML em uma organização, pode usar constantes do LookML para compartilhar regras de negócios padrão, glossários ou requisitos de filtragem em definições de agentes sem duplicar texto.

Para usar uma constante nas instruções do agente, siga estas etapas:

  1. Defina a constante no arquivo manifest.lkml do projeto:

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

  2. Referencie a constante no parâmetro instructions do agente do painel usando a sintaxe @{<var>CONSTANT_NAME</var>}:

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

Quando o agente processa consultas, o Looker substitui dinamicamente a string constante nas instruções do agente.

Associar um agente de dashboard a um dashboard do LookML

Para anexar um agente de dashboard a um dashboard do LookML, configure os parâmetros no nível do dashboard no arquivo .dashboard.lookml.

Os seguintes parâmetros de painel controlam o comportamento do agente para dashboards do LookML:

  • enabled_dashboard_agent: (opcional) aceita true ou false. Determina se os usuários podem ver o ícone Spark Conversar com este painel e interagir com o agente do painel. Se omitido, o padrão desse parâmetro será true na camada da API.
  • default_dashboard_agent: (opcional) especifica o nome do agente do LookML (definido com o parâmetro agent) que serve como agente padrão para o painel.

Exemplo de configuração de dashboard do LookML

O snippet a seguir mostra como mapear o sales_dashboard_agent para um painel do LookML:

- dashboard: executive_sales_overview
  title: "Executive Sales Overview"
  layout: newspaper
  enabled_dashboard_agent: true
  default_dashboard_agent: sales_dashboard_agent

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

Se enabled_dashboard_agent estiver definido como true e nenhum default_dashboard_agent for especificado, os usuários ainda poderão conversar com o painel. O agente será executado sem instruções personalizadas.

Testar agentes de dashboards do LookML no modo de desenvolvimento

Se o agente já tiver sido implantado na produção, os desenvolvedores do LookML poderão modificar as instruções do agente e testar as respostas de forma iterativa diretamente na interface do Looker antes de implantar as mudanças na produção.

Para testar mudanças em um agente de painel do LookML no modo de desenvolvimento, siga estas etapas:

  1. Verifique se o agente tem pelo menos uma definição de base implantada na produção.
  2. Ative o Modo de Desenvolvimento.
  3. Edite o agente instructions ou as configurações no arquivo LookML e salve as mudanças.
  4. Abra o dashboard do LookML na interface do Looker.
  5. Selecione brilho Conversar com este painel para abrir o painel de chat.
  6. Faça perguntas para testar como o agente interpreta e responde aos seus comandos.

Quando o modo de desenvolvimento está ativado, a Análise Conversacional faz referência à definição do agente na memória, à definição do painel do LookML e aos arquivos de modelo da sua ramificação de desenvolvimento. Quando você desativa o modo de desenvolvimento, a análise de conversas volta a fazer referência às definições implantadas da ramificação de produção.

Todo o histórico de conversas criado durante o modo de desenvolvimento é mantido e fica visível na lista de conversas recentes entre as sessões.

Copiar o LookML do agente de dashboard dos painéis definidos pelo usuário

Se você criar um protótipo de painel como um painel definido pelo usuário na UI, poderá exportar a configuração completa dele, incluindo as configurações e instruções do agente de dashboard, para o código LookML.

Para copiar o LookML de um painel definido pelo usuário:

  1. Abra o painel definido pelo usuário.
  2. Selecione o menu de três pontos more_vert Ações do painel e escolha Acessar o LookML.
  3. Na caixa de diálogo Acessar o LookML, copie o LookML do dashboard gerado e o código de definição do agente do dashboard.
  4. Cole o LookML do dashboard em um arquivo .dashboard.lookml e o bloco agent no arquivo LookML do modelo ou do agente.

A LookML exportada preserva o estado da opção Ativar chat com o painel usando o valor do parâmetro enabled_dashboard_agent junto com instruções personalizadas do agente.

Conferir detalhes do agente na interface do Looker

Ao visualizar um dashboard do LookML com um agente de dashboard ativo, é possível inspecionar a configuração do agente no painel de chat:

  1. Selecione spark Converse com este painel.
  2. Selecione ajustar Gerenciar agente.

Para painéis do LookML, o painel Gerenciar agente mostra instruções do agente, o status do Advanced Analytics e opções de depuração no modo somente leitura. Não é possível editar as configurações diretamente na UI.

Para editar a configuração, os desenvolvedores com a permissão develop nos modelos subjacentes podem clicar em Editar em LookML para navegar diretamente até o arquivo LookML relevante no IDE.

Consultar um dashboard do LookML com um agente de dashboard

Para iniciar uma conversa com um agente do painel do LookML:

  1. Abra o painel do LookML.
  2. Selecione spark Converse com este painel.
  3. No campo Fazer uma pergunta, insira sua consulta em linguagem natural.
  4. Se show_thinking for permitido para seu agente de painel, escolha um modo de pergunta:
    • Rápido: traduz rapidamente sua consulta em pesquisas diretas de métricas do LookML.
    • Pensamento: avalia questões analíticas complexas e mostra o raciocínio etapa por etapa.
  5. Clique em enviar Enviar.

Para cancelar uma consulta em andamento, clique em Interromper resposta.

Gerenciar conversas

  • Conversas recentes: para abrir conversas anteriores, selecione more_vert Menu > Conversas recentes.
  • Renomear uma conversa: selecione more_vert ao lado de uma conversa e selecione Editar Renomear.
  • Excluir uma conversa: selecione more_vert ao lado de uma conversa e selecione delete Excluir.

Limitações dos agentes de dashboard do LookML

Os agentes de painel do LookML têm as seguintes limitações:

  • Definidos apenas em LookML: os agentes de dashboard do LookML precisam ser declarados em LookML. Não é possível criar, configurar ou editar esses elementos na interface do Looker.
  • Consultas verificadas não são compatíveis: os agentes de dados para painéis do LookML não são compatíveis com consultas verificadas.
  • Requisito de mesmo projeto: o agente precisa ser definido no mesmo projeto do LookML que o painel que o referencia.
  • Um agente por dashboard: é possível associar apenas um agente de dashboard a um dashboard do LookML.
  • Somente agentes de painel: o LookML não oferece suporte à criação de agentes de dados da Análise. Todas as declarações agent em LookML precisam incluir is_dashboard_agent: yes.
  • Análise avançada no Looker 26.14: os agentes de painel do LookML no Looker 26.14 não são compatíveis com o parâmetro advanced_analytics.
  • Modo de Desenvolvimento e agentes não implantados: a interface de conversa ignora as mudanças feitas no Modo de Desenvolvimento na configuração de agentes de painel do LookML que ainda não foram implantados na produção.