Estudo Aprofundado
Databricks Genie

Genie é a experiência de IA da Databricks para trabalhar com dados em linguagem natural. Dá a qualquer usuário da organização um único lugar para fazer perguntas sobre dados em linguagem natural, explorar dashboards de AI/BI e rodar Databricks Apps — tudo com respostas fundamentadas nos dados da organização e governadas via Unity Catalog.

A família Genie

• Genie One — interface simplificada para usuários de negócio descobrirem e interagirem com ativos de dados (chat unificado sobre dados, dashboards e apps).
• Genie Agents — ambientes específicos de domínio onde times de dados configuram dados confiáveis, métricas e regras de negócio que alimentam as respostas do Genie One. Este é o antigo "Genie Spaces".
• Genie Code — assistente de IA para código e dados, voltado a desenvolvedores dentro do workspace Databricks (notebooks, SQL editor, Lakeflow Pipelines Editor, dashboards de AI/BI, MLflow).

Também existe Genie mobile (acesso via iOS/Android) e uma versão account-level do Genie One, que permite descobrir e interagir com ativos compartilhados entre todos os workspaces de uma conta.

3.1 Conceito

Um Genie Agent é uma interface de chat em linguagem natural, específica de domínio, na qual usuários fazem perguntas sobre seus dados e recebem de volta consultas SQL, tabelas de resultado e visualizações. Analistas de dados curam cada agente com datasets registrados no Unity Catalog, exemplos de consultas SQL, expressões SQL para semântica de negócio e instruções em texto adaptadas à terminologia da organização.

3.2 Como funciona (fluxo conceitual)

Quando um usuário envia uma pergunta, o Genie:

1. Interpreta (parse) a solicitação;
2. Identifica as fontes de dados relevantes;
3. Determina como gerar uma resposta apropriada;
4. Gera uma consulta SQL (sempre somente leitura) que roda no SQL warehouse do agente;
5. Se não conseguir gerar uma resposta, pode fazer perguntas de esclarecimento antes de responder.

3.3 Componentes usados para gerar uma resposta

3.4 Conceitos-chave (glossário técnico)

3.5 Que dados posso usar?

Um Genie Agent é baseado em dados registrados no Unity Catalog: tabelas gerenciadas, tabelas externas, tabelas foreign, views, metric views e materialized views.

3.6 Melhoria de precisão: Inspect Public Preview

Inspect usa raciocínio avançado para revisar e melhorar a precisão da SQL gerada:

1. Revisa a consulta SQL gerada inicialmente;
2. Escreve instruções SQL menores para verificar aspectos específicos (filtros, intervalos de data, joins, agregações);
3. Identifica lacunas ou problemas potenciais;
4. Se necessário, gera uma consulta melhorada;
5. Compara a original com a melhorada;
6. Retorna a que responde com mais precisão.

Use Inspect quando quiser confiança adicional em consultas complexas (múltiplos filtros, intervalos de data, múltiplas tabelas).

3.7 Agent mode antigo Research Agent

Permite respostas a perguntas complexas e exploratórias usando raciocínio multi-etapas e teste de hipóteses:

• Cria planos de pesquisa — desenvolve abordagem estruturada e hipóteses
• Executa múltiplas consultas — várias SQLs para reunir evidências de diferentes ângulos
• Aprende e itera — ajusta a abordagem com base no que descobre
• Entrega relatórios abrangentes — com citações, visualizações e tabelas de suporte

Também responde sobre arquivos não estruturados em Unity Catalog Volumes anexados ao agente, e pode ser acionado programaticamente via Agent mode APIs (Beta).

5.1 Fluxo básico de criação

1. Clique em Genie Agents na barra lateral;
2. Clique em New;
3. Escolha as fontes de dados (tabelas/views do Unity Catalog);
4. Clique em Create.

5.2 Setup assistido por Genie Code

Ao criar um agente, o Genie Code é acionado automaticamente: lê os dados e sugere contexto (descrições de tabela, exemplos de consulta). Você revisa e aceita as sugestões, ou pede para preencher lacunas específicas. Também é possível pedir ao Genie Code para criar o agente inteiro a partir de uma descrição em linguagem natural, sem saber de antemão quais tabelas usar.

Create a Genie agent for our sales team that answers questions about
weekly revenue, units sold, and returns by store and region.
Use the sales and store tables in the retail catalog.

5.3 Revisão de consultas sugeridas

Ao adicionar dados a um agente, o Genie busca automaticamente consultas populares do workspace associadas àqueles ativos (usando as credenciais do usuário, respeitando CAN VIEW). As sugestões aparecem na aba Data do painel Instructions, e podem ser aceitas ou rejeitadas uma a uma.

5.4 Configurações do agente

Em Configure → Settings:

5.5 Compartilhamento

Novos agentes são salvos na pasta pessoal do usuário por padrão, herdando permissões da pasta. É possível compartilhar com usuários/grupos específicos (CAN MANAGE, CAN EDIT, CAN RUN, CAN VIEW) ou com todos os usuários da conta. Também há suporte a OpenSharing para compartilhar com usuários fora da organização.

5.6 Outras ações (menu kebab)

• Clonar — cópia independente com tabelas, configurações, instruções gerais, exemplos SQL e funções SQL. Threads de chat e dados de monitoramento não são copiados.
• Exportar como metric view — cria uma metric view a partir do contexto/dados configurados no agente.
• Certificar/depreciar — usa a tag governada system.certification_status do Unity Catalog.

A API do Genie oferece dois tipos de capacidade:

• Conversation APIs — consultas em linguagem natural com estado (follow-up e histórico), para chatbots, agentes e aplicações
• Management APIs — criação, configuração e deploy programático de agentes entre workspaces, para CI/CD e controle de versão

7.1 Pré-requisitos

• Workspace com entitlement Databricks SQL
• Ao menos CAN USE em um SQL warehouse pro/serverless
• Autenticação via OAuth U2M (usuário com browser) ou OAuth M2M (service principal, sem browser)

7.2 Criar um Genie Agent via API (Management API)

POST /api/2.0/genie/spaces
Host: <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>

{
  "description": "Space for analyzing sales performance and trends",
  "parent_path": "/Workspace/Users/<username>",
  "title": "Sales Analytics Space",
  "warehouse_id": "<warehouse-id>",
  "serialized_space": "<JSON escapado — ver 7.3>"
}

7.3 O campo serialized_space

String JSON que define toda a configuração do agente. Estrutura (versão 2, atual):

{
  "version": 2,
  "config": {
    "sample_questions": [
      { "id": "a1b2c3d4e5f60000000000000000000a", "question": ["What were total sales last month?"] }
    ]
  },
  "data_sources": {
    "tables": [
      {
        "identifier": "sales.analytics.customers",
        "description": ["Customer master data..."],
        "column_configs": [
          { "column_name": "customer_id", "synonyms": ["cust_id", "account_id"] },
          { "column_name": "customer_name", "enable_entity_matching": true },
          { "column_name": "internal_notes", "exclude": true }
        ]
      }
    ],
    "metric_views": [
      { "identifier": "sales.analytics.revenue_metrics" }
    ]
  },
  "instructions": {
    "text_instructions": [
      { "id": "01f0b37c378e1c9100000000000000a1", "content": ["When calculating revenue, sum order_amount..."] }
    ],
    "example_question_sqls": [
      {
        "id": "01f0821116d912db00000000000000b1",
        "question": ["Show top 10 customers by revenue"],
        "sql": ["SELECT customer_name, SUM(order_amount) AS total_revenue\n",
                "FROM sales.analytics.orders o\n",
                "JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\n",
                "GROUP BY customer_name\n",
                "ORDER BY total_revenue DESC\n",
                "LIMIT 10"]
      }
    ],
    "join_specs": [
      {
        "id": "01f0c0b4e815100000000000000000c1",
        "left":  { "identifier": "sales.analytics.orders",    "alias": "orders" },
        "right": { "identifier": "sales.analytics.customers", "alias": "customers" },
        "sql": ["`orders`.`customer_id` = `customers`.`customer_id`", "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--"]
      }
    ],
    "sql_snippets": {
      "expressions": [{ "id": "...", "alias": "order_year", "sql": ["YEAR(orders.order_date)"] }],
      "measures":    [{ "id": "...", "alias": "total_revenue", "sql": ["SUM(orders.order_amount)"] }]
    }
  },
  "benchmarks": {
    "questions": [
      { "id": "...", "question": ["What is the average order value?"],
        "answer": [{ "format": "SQL", "content": ["SELECT AVG(order_amount) AS avg_order_value\n", "FROM sales.analytics.orders"] }] }
    ]
  }
}

Regras de validação importantes (rejeitadas se violadas)

• IDs: string hexadecimal minúscula de 32 caracteres (formato UUID sem hífens)
• Ordenação obrigatória: arrays como data_sources.tables, text_instructions, example_question_sqls, join_specs, sql_snippets.* e benchmarks.questions devem vir pré-ordenados alfabeticamente por id (ou identifier) — a API rejeita arrays não ordenados
• Unicidade: IDs de sample_questions + benchmarks.questions únicos entre si; IDs de instructions únicos entre si; (table_identifier, column_name) único
• Limites: strings até 25.000 caracteres; arrays até 10.000 itens; no máximo 1 text instruction por agente (bloco único, não um texto por linha)
• join_specs.sql: exatamente dois elementos — condição de join (aliases entre crases) + anotação "--rt=FROM_RELATIONSHIP_TYPE_<CARDINALIDADE>--". Valores válidos: MANY_TO_ONE, ONE_TO_MANY, ONE_TO_ONE, MANY_TO_MANY. Omitir a anotação causa erro de parsing.
• Identificadores de tabela: formato de três níveis (catalog.schema.table)
• Benchmarks: cada pergunta com exatamente uma resposta format: "SQL"

7.4 Usando a Conversation API

Iniciar uma conversa:

POST /api/2.0/genie/spaces/{space_id}/start-conversation
{ "content": "<sua pergunta>" }

Retorna conversation.id e message.id para consultas subsequentes.

Consultar status/SQL gerada (polling):

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}

Recuperar resultados da consulta:

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/query-result/{attachment_id}

Visualização (Beta): definir enable_visualization: true ao iniciar a conversa/criar mensagem; attachments passa a incluir um objeto viz (GenieVizAttachment), baixável via endpoint de download-visualization.

Perguntas de follow-up (mantém contexto/histórico):

POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages
{ "content": "Which of these customers opened and forwarded the email?" }

• Trusted asset? verifique se attachments contém query.parameters — presença indica uso de trusted asset
• Raciocínio do Genie: verifique attachments para query_attachments do tipo GenieQueryAttachments

7.5 Boas práticas de uso da API

• Implementar retry com backoff exponencial (a API não reenvia falhas automaticamente)
• Logar requests/responses para debug, monitoramento e custo
• Poll a cada 1–5s, com backoff exponencial até 1 min, limitando a 10 minutos
• Nova conversa a cada sessão — reutilizar threads entre sessões reduz precisão por reuso indevido de contexto
• Gerenciar o limite de 10.000 conversas: listar, identificar obsoletas, deletar via DELETE .../conversations/{conversation_id}

Esta seção traduz a arquitetura em cenários concretos — organizados por padrão de uso.

Seção adicionada em setembro/2026: Scheduled Tasks é a novidade mais relevante do Genie Code desde seu lançamento, e ainda não existia quando o restante deste documento foi escrito — vale ler mesmo se você já conhece o Genie Code "clássico" (o antigo Databricks Assistant, ver nota 00).

12.1 Linha do tempo

• 11 de março de 2026 — lançamento oficial do Genie Code, descrito pela Databricks como "an autonomous AI agent that fundamentally changes how data work gets done" (comunicado de imprensa).
• 17 de junho de 2026 (Data + AI Summit 2026) — anúncio do Full-Page Command Center, integrações mais profundas com MLflow/Model Serving, provisionamento de compute consciente da tarefa (GPU sob demanda), e o recurso de Scheduled Tasks, divulgado então como "coming soon".
• 8 de julho de 2026, 00:00 UTC — início da cobrança pay-as-you-go do Genie Code (ver 12.8).
• Hoje — Scheduled Tasks já está documentado oficialmente como recurso beta, exigindo aprovação do admin do workspace na página de Previews.

12.2 Genie Code em detalhe (recap)

Diferente do Genie Agents (self-service via chat para usuários de negócio), o Genie Code é voltado a quem escreve código: aparece como painel em notebooks, SQL Editor, Lakeflow Pipelines Editor, dashboards de AI/BI, MLflow e num editor de arquivos. Abre-se pelo ícone de sparkle no canto superior direito da superfície, ou pelo atalho Cmd+I (macOS) / Ctrl+I (Windows) dentro de notebooks.

Por padrão opera em Agent Mode: planeja a solução, busca ativos relevantes (tabelas, notebooks, jobs), roda código, usa o resultado das células para refinar a resposta e corrige erros sozinho — sem exigir aprovação manual a cada micro-passo. Para voltar a um modo só-consultivo, basta pedir algo como "Just explain this to me, don't run any code."

12.3 Sistema de aprovação de ferramentas

Por padrão, o Genie Code pede aprovação antes de usar qualquer ferramenta (rodar uma célula, criar um arquivo, etc.). As opções configuráveis são:

12.4 O que são as Scheduled Tasks

Scheduled Tasks deixam o Genie Code trabalhar enquanto você não está olhando: você define um prompt (e, opcionalmente, um ativo relevante — notebook, workflow ou dashboard) e uma agenda; quando a task roda, o Genie Code executa uma sessão completa e entrega os resultados numa conversa nova, pronta para revisão, refinamento ou continuação interativa.

12.5 Como criar uma Scheduled Task

Três formas, todas dentro do painel Scheduled tasks (ícone de calendário no Full-Page Genie Code):

1. Linguagem natural — peça direto no chat; o Genie pode fazer perguntas de esclarecimento antes de criar a task.
2. Sugeridas — o painel oferece uma lista de tasks prontas com base no contexto do workspace.
3. Manual — "Create manually" no painel, preenchendo Title, Prompt, Schedule e Timezone.

Every morning at 6 AM, check last night's job runs, summarize failures
and anomalies, and flag anything that needs my attention today.

12.6 Gerenciando tasks já criadas

• Disparo manual — botão de play, sem esperar o horário agendado;
• Pausar — desliga a task sem apagá-la;
• Editar — título, prompt, agenda ou timezone;
• Excluir — via menu kebab;
• Histórico — cada execução fica registrada, com acesso ao chat individual daquela rodada.

12.7 Casos de uso citados pela Databricks

12.8 Genie Code como task de Job (Databricks Workflows)

Além das Scheduled Tasks (nativas do próprio Genie Code, seção 12.4), existe um recurso relacionado mas distinto: o Genie Code task é um tipo de tarefa que pode ser adicionado a um Job/Workflow multi-task do Databricks, ao lado de tarefas do tipo Notebook, Python, SQL ou dbt. Ao rodar, ele "lança um novo chat do Genie Code com seu prompt e produz uma resposta", de forma não-assistida, dentro do DAG do job.

Configura-se com um prompt em linguagem natural descrevendo a ação desejada — útil para automatizar passos como analisar anomalias nos dados, resumir resultados de outras tasks do job, ou gerar relatórios de compliance como parte de um pipeline já orquestrado.

12.9 Pricing do Genie Code

A partir de 8 de julho de 2026, 00:00 UTC, o Genie Code passou a ser cobrado em modelo pay-as-you-go, sem mensalidade fixa por usuário: