Genie plugin

Integra spaces do Databricks AI/BI Genie à sua aplicação AppKit, permitindo consultas a dados em linguagem natural por meio de uma interface conversacional.

Principais recursos:

Aliases nomeados para múltiplos spaces do Genie
Streaming via SSE com atualizações de status em tempo real
Replay do histórico de conversas com reconexão automática
Busca de anexos com resultados de queries
Execução em nome do usuário (on-behalf-of, OBO)

Uso básico

import { createApp, genie, server } from "@databricks/appkit";

await createApp({
  plugins: [
    server(),
    genie(),
  ],
});

Opções de configuração

Opção	Tipo	Padrão	Descrição
`spaces`	`Record<string, string>`	`{ default: DATABRICKS_GENIE_SPACE_ID }`	Mapeamento de aliases para IDs de Genie Space
`timeout`	`number`	`120000`	Tempo limite de polling em ms. Defina como `0` para tempo indefinido

Aliases de space

Os aliases de space permitem referenciar vários spaces do Genie pelo nome. O alias é usado nas rotas de API e no componente de frontend <GenieChat>:

genie({
  spaces: {
    sales: "01ABCDEF12345678",
    support: "01GHIJKL87654321",
  },
});

Se você omitir spaces, o plugin lê DATABRICKS_GENIE_SPACE_ID do ambiente e o registra com o alias default.

Como encontrar o Space ID do Genie

Você encontra o Space ID na aba About da página do seu space do Genie no Databricks:

Space ID do Genie na aba About

Variáveis de ambiente

Variável	Descrição
`DATABRICKS_GENIE_SPACE_ID`	ID do Genie Space padrão (usado quando a configuração `spaces` é omitida)

Endpoints HTTP

O plugin genie expõe estes endpoints (montados em /api/genie):

POST /api/genie/:alias/messages — Envia uma mensagem para um space do Genie (stream SSE)
GET /api/genie/:alias/conversations/:conversationId — Reproduz o histórico da conversa (stream SSE)

Enviar uma mensagem

POST /api/genie/:alias/messages
Content-Type: application/json

{
  "content": "What were total sales last quarter?",
  "conversationId": "optional-existing-conversation-id"
}

A resposta é um stream SSE que emite estes tipos de evento:

Tipo de evento	Descrição
`message_start`	IDs de conversa e de mensagem atribuídos
`status`	Atualizações do status de processamento (ex.: `ASKING_AI`, `EXECUTING_QUERY`)
`message_result`	Mensagem final com texto e anexos de consulta
`query_result`	Dados tabulares de um anexo de consulta
`error`	Detalhes do erro

Obter o histórico da conversa

GET /api/genie/:alias/conversations/:conversationId

Retorna um stream SSE com eventos message_result e query_result para todas as mensagens da conversa.

Acesso programático

O plugin exporta sendMessage e getConversation para uso no lado do servidor:

const AppKit = await createApp({
  plugins: [server(), genie({ spaces: { demo: "space-id" } })],
});

// Transmitir eventos
for await (const event of AppKit.genie.sendMessage("demo", "Show revenue by region")) {
  console.log(event.type, event);
}

// Obter a conversa completa
const history = await AppKit.genie.getConversation("demo", "conversation-id");

Componentes de frontend

O pacote @databricks/appkit-ui oferece componentes React prontos para uso com o Genie:

GenieChat

Uma interface de chat completa que cuida do streaming, do histórico e da reconexão:

Componente GenieChat

import { GenieChat } from "@databricks/appkit-ui/react";

function GeniePage() {
  return (
    <div style={{ height: 600 }}>
      <GenieChat alias="demo" />
    </div>
  );
}

A prop alias deve corresponder a uma chave da configuração spaces no servidor.

Hook useGenieChat

Para interfaces de chat personalizadas, use o hook useGenieChat diretamente:

import { useGenieChat } from "@databricks/appkit-ui/react";

function CustomChat() {
  const { messages, status, sendMessage, reset } = useGenieChat({
    alias: "demo",
  });

  return (
    <>
      {messages.map((msg) => (
        <div key={msg.id}>{msg.content}</div>
      ))}
      <button onClick={() => sendMessage("Show top customers")}>Ask</button>
      <button onClick={reset}>New conversation</button>
    </>
  );
}

Consulte a referência do componente GenieChat para ver a API completa de props.