Genie Agents

Ofrece a tus usuarios un cuadro de chat que consulta tus datos. Sin text-to-SQL, sin mapeo de esquemas, sin LLM personalizado. Un Genie Agent (antes Genie space) es una interfaz de lenguaje natural de Databricks sobre tablas de Unity Catalog: conjuntos de datos curados, más un almacén de conocimiento (sinónimos, SQL de ejemplo, descripciones de columnas), más un sistema de IA compuesto que convierte las preguntas en SQL. Tu aplicación de AppKit lo integra con un plugin en el servidor y un componente en la página.

Para probar un Genie Agent en el workspace antes de integrarlo, consulta Usar un Genie Agent. Para crear o gestionar uno desde tu agente de programación, usa la agent skill databricks-genie-agents.

Requisitos previos

• Databricks CLI v1.0.0+ con un perfil autenticado.
• Una app de AppKit en ejecución. Consulta el Inicio rápido de Apps.

• Un Genie Agent configurado sobre tablas de Unity Catalog. Consulta Create and manage a Genie Agent para configurarlo.

  Adjunta el agente como recurso en la configuración de la app (interfaz o CLI) con Can run seleccionado, y Databricks otorgará ese permiso al service principal de tu app. Después, app.yaml vincula el recurso a una variable de entorno. Los permisos del usuario final se explican más adelante.

Por qué Genie

De la pregunta al resultado, Genie:

• Entiende tu esquema a partir de tablas de Unity Catalog, sinónimos, ejemplos de SQL y descripciones de columnas.
• Genera SQL a partir de preguntas en lenguaje natural, y pide aclaraciones cuando el prompt es ambiguo.
• Ejecuta la consulta en tu warehouse y devuelve resultados tabulares listos para renderizar.

El plugin genie conecta todo eso con tu interfaz de chat y se encarga del streaming por SSE, la autenticación y la reproducción de conversaciones.

Conectar el plugin

Registra el plugin con uno o más alias de space. Las claves de alias se convierten en la prop alias del componente de frontend.

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

await createApp({
  plugins: [
    server(),
    genie({
      spaces: {
        sales: process.env.SALES_GENIE_SPACE_ID!,
      },
    }),
  ],
});

Vincula cada alias a un recurso de Genie Agent en app.yaml:

env:
  - name: SALES_GENIE_SPACE_ID
    valueFrom: genie-space

El runtime de Databricks Apps inyecta el ID del space del recurso en la variable de entorno. Puedes encontrar el ID de tu space en la pestaña Settings de la página del Genie Agent en tu workspace.

Para una aplicación de un solo agente, omite por completo la configuración de spaces y vincula la variable de entorno predeterminada del plugin:

env:
  - name: DATABRICKS_GENIE_SPACE_ID
    valueFrom: genie-space

Si no se pasa spaces, el plugin lee DATABRICKS_GENIE_SPACE_ID y lo registra con el alias default.

Renderizar el componente de chat

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

export function ChatPage() {
  return (
    <div style={{ height: 600 }}>
      <GenieChat alias="sales" />
    </div>
  );
}

La prop alias debe coincidir con una clave de la configuración spaces del servidor. <GenieChat> ocupa todo el espacio de su contenedor padre, así que colócalo en un contenedor de altura fija o su altura se reducirá a cero. El componente renderiza los mensajes, gestiona el streaming, conserva el ID de la conversación en la URL y restaura el historial al recargar. Consulta la referencia de GenieChat para ver la lista completa de props.

Interfaz personalizada con useGenieChat

Para crear una interfaz de chat personalizada, usa el hook directamente. Devuelve el mismo flujo de mensajes junto con el estado del ciclo de vida de la solicitud.

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

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

  return (
    <>
      {messages.map((msg) => (
        <div key={msg.id} data-role={msg.role}>
          {msg.content}
        </div>
      ))}
      <button
        onClick={() => sendMessage("What were total sales last quarter?")}
        disabled={status === "streaming"}
      >
        Ask
      </button>
      <button onClick={reset}>New conversation</button>
    </>
  );
}

status alterna entre idle, streaming, loading-history, loading-older y error. Úsalo para gestionar los estados de carga en tu interfaz. El hook también devuelve error, conversationId y utilidades de paginación (hasPreviousPage, isFetchingPreviousPage, fetchPreviousPage). Consulta la referencia del plugin Genie de AppKit para ver el tipo de retorno completo y la API de conversación de Genie para la API REST subyacente.

Múltiples spaces

Registra más de un space para que tus usuarios puedan alternar entre dominios; por ejemplo, un space de ventas y otro de soporte en la misma aplicación.

genie({
  spaces: {
    sales: process.env.SALES_GENIE_SPACE_ID!,
    support: process.env.SUPPORT_GENIE_SPACE_ID!,
  },
}),

Vincula cada ID a un recurso independiente en app.yaml. Consulta el template Genie Multi-Agent Selector para ver una interfaz funcional con cambio de agente, limpieza de conversaciones y sincronización de la URL.

Permisos y acceso a datos

El plugin genie llama a la API de Genie en nombre del usuario que ha iniciado sesión. Para que una solicitud se complete correctamente, tanto el service principal de la aplicación como cada usuario final necesitan acceso:

• Service principal de la aplicación: CAN RUN sobre el Genie Agent, que se concede al adjuntar el agente como recurso de la aplicación (desde la interfaz o la CLI) con Can run seleccionado. Los permisos sobre los datos subyacentes no se aprovisionan automáticamente: concede al service principal USE CATALOG, USE SCHEMA y SELECT sobre las tablas de Unity Catalog por separado. Consulta Add a Genie Agent resource to an app.
• Usuarios finales: acceso al Genie Agent (compartido con ellos o a través de un grupo) y SELECT sobre esas mismas tablas. Si el usuario no tiene acceso, la llamada devuelve un 403. No tienes que escribir la comprobación de permisos.

Qué sigue

Prueba la Genie Analytics App para ver una configuración completa ya integrada, o explora los endpoints de agentes personalizados para Knowledge Assistants y Supervisor Agents.