Plugin Genie

Intègre les spaces Databricks AI/BI Genie à votre application AppKit, permettant d'interroger les données en langage naturel via une interface conversationnelle.

Fonctionnalités clés :

Alias nommés pour plusieurs spaces Genie
Streaming SSE avec mises à jour de statut en temps réel
Rejeu de l'historique des conversations avec reconnexion automatique
Récupération des pièces jointes des résultats de requête
Exécution pour le compte de l'utilisateur (on-behalf-of, OBO)

Utilisation de base

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

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

Options de configuration

Option	Type	Valeur par défaut	Description
`spaces`	`Record<string, string>`	`{ default: DATABRICKS_GENIE_SPACE_ID }`	Table de correspondance entre alias et identifiants de space Genie
`timeout`	`number`	`120000`	Délai d'expiration de l'interrogation périodique, en ms. Définir à `0` pour un délai illimité

Alias de space

Les alias de space permettent de référencer plusieurs spaces Genie par leur nom. L'alias est utilisé dans les routes d'API ainsi que dans le composant frontend <GenieChat> :

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

Si vous omettez spaces, le plugin lit la variable d'environnement DATABRICKS_GENIE_SPACE_ID et l'enregistre sous l'alias default.

Trouver l'ID de votre space Genie

L'ID du space se trouve dans l'onglet About de la page de votre space Genie dans Databricks :

ID du space Genie dans l'onglet About

Variables d'environnement

Variable	Description
`DATABRICKS_GENIE_SPACE_ID`	ID du space Genie par défaut (utilisé lorsque la configuration `spaces` est omise)

Endpoints HTTP

Le plugin genie expose les endpoints suivants (montés sous /api/genie) :

POST /api/genie/:alias/messages — Envoyer un message à un space Genie (flux SSE)
GET /api/genie/:alias/conversations/:conversationId — Rejouer l'historique de la conversation (flux SSE)

Envoyer un message

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

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

La réponse est un flux SSE qui émet les types d'événements suivants :

Type d'événement	Description
`message_start`	Identifiants de conversation et de message attribués
`status`	Mises à jour de l'état du traitement (par ex. `ASKING_AI`, `EXECUTING_QUERY`)
`message_result`	Message final avec le texte et les pièces jointes de requête
`query_result`	Données tabulaires d'une pièce jointe de requête
`error`	Détails de l'erreur

Récupérer l'historique de la conversation

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

Renvoie un flux SSE d'événements message_result et query_result pour tous les messages de la conversation.

Accès programmatique

Le plugin exporte sendMessage et getConversation pour une utilisation côté serveur :

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

// Diffuser les événements en streaming
for await (const event of AppKit.genie.sendMessage("demo", "Show revenue by region")) {
  console.log(event.type, event);
}

// Récupérer la conversation complète
const history = await AppKit.genie.getConversation("demo", "conversation-id");

Composants frontend

Le package @databricks/appkit-ui fournit des composants React prêts à l'emploi pour Genie :

GenieChat

Une interface de chat complète qui gère le streaming, l'historique et la reconnexion :

Composant GenieChat

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

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

La propriété alias doit correspondre à une clé de la configuration spaces définie sur le serveur.

Hook useGenieChat

Pour des interfaces de chat personnalisées, utilisez directement le 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>
    </>
  );
}

Consultez la référence du composant GenieChat pour l'API complète des propriétés.