Genie plugin

Integra los spaces de Databricks AI/BI Genie en tu aplicación AppKit, lo que permite realizar queries de datos en lenguaje natural mediante una interfaz conversacional.

Características principales:

Alias con nombre para varios spaces de Genie
Streaming por SSE con actualizaciones de estado en tiempo real
Reproducción del historial de conversaciones con reconexión automática
Obtención de adjuntos con resultados de queries
Ejecución en nombre del usuario (OBO)

Uso básico

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

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

Opciones de configuración

Opción	Tipo	Valor predeterminado	Descripción
`spaces`	`Record<string, string>`	`{ default: DATABRICKS_GENIE_SPACE_ID }`	Mapa de alias a IDs de spaces de Genie
`timeout`	`number`	`120000`	Tiempo de espera del polling en ms. Usa `0` para que sea indefinido

Alias de spaces

Los alias de spaces te permiten hacer referencia a varios spaces de Genie por su nombre. El alias se usa en las rutas de la API y en el componente de frontend <GenieChat>:

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

Si omites spaces, el plugin lee DATABRICKS_GENIE_SPACE_ID del entorno y lo registra con el alias default.

Cómo encontrar el ID de tu Genie Space

Encontrarás el Space ID en la pestaña About de la página de tu Genie space en Databricks:

ID del Genie Space en la pestaña About

Variables de entorno

Variable	Descripción
`DATABRICKS_GENIE_SPACE_ID`	ID del Genie Space predeterminado (se usa cuando se omite la configuración `spaces`)

Endpoints HTTP

El plugin de genie expone estos endpoints (montados en /api/genie):

POST /api/genie/:alias/messages — Envía un mensaje a un space de Genie (stream SSE)
GET /api/genie/:alias/conversations/:conversationId — Reproduce el historial de la conversación (stream SSE)

Enviar un mensaje

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

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

La respuesta es un stream SSE que emite estos tipos de eventos:

Tipo de evento	Descripción
`message_start`	IDs de conversación y mensaje asignados
`status`	Actualizaciones del estado de procesamiento (p. ej., `ASKING_AI`, `EXECUTING_QUERY`)
`message_result`	Mensaje final con el texto y los adjuntos de la consulta
`query_result`	Datos tabulares de un adjunto de consulta
`error`	Detalles del error

Obtener el historial de la conversación

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

Devuelve un stream SSE de eventos message_result y query_result para todos los mensajes de la conversación.

Acceso programático

El plugin exporta sendMessage y getConversation para su uso en el servidor:

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

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

// Obtener la conversación completa
const history = await AppKit.genie.getConversation("demo", "conversation-id");

Componentes de frontend

El paquete @databricks/appkit-ui ofrece componentes de React listos para usar con Genie:

GenieChat

Una interfaz de chat completa que gestiona el streaming, el historial y la reconexión:

Componente GenieChat

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

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

La prop alias debe coincidir con una clave de la configuración spaces del servidor.

Hook useGenieChat

Para interfaces de chat personalizadas, usa directamente el hook useGenieChat:

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>
    </>
  );
}

Consulta la referencia del componente GenieChat para ver la API completa de props.