Genie plugin

Integrates Databricks AI/BI Genie spaces into your AppKit application, enabling natural language data queries via a conversational interface.

Key features:

• Named space aliases for multiple Genie spaces
• SSE streaming with real-time status updates
• Conversation history replay with automatic reconnection
• Query result attachment fetching
• On-behalf-of (OBO) user execution

Basic usage

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

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

Configuration options

Option	Type	Default	Description
spaces	Record<string, string>	{ default: DATABRICKS_GENIE_SPACE_ID }	Map of alias names to Genie Space IDs
timeout	number	120000	Polling timeout in ms. Set to 0 for indefinite

Space aliases

Space aliases let you reference multiple Genie spaces by name. The alias is used in API routes and the frontend <GenieChat> component:

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

If you omit spaces, the plugin reads DATABRICKS_GENIE_SPACE_ID from the environment and registers it under the default alias.

Environment variables

Variable	Description
DATABRICKS_GENIE_SPACE_ID	Default Genie Space ID (used when spaces config is omitted)

HTTP endpoints

The genie plugin exposes these endpoints (mounted under /api/genie):

• POST /api/genie/:alias/messages — Send a message to a Genie space (SSE stream)
• GET /api/genie/:alias/conversations/:conversationId — Replay conversation history (SSE stream)

Send a message

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

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

The response is an SSE stream that emits these event types:

Event type	Description
message_start	Conversation and message IDs assigned
status	Processing status updates (e.g. ASKING_AI, EXECUTING_QUERY)
message_result	Final message with text and query attachments
query_result	Tabular data for a query attachment
error	Error details

Get conversation history

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

Returns an SSE stream of message_result and query_result events for all messages in the conversation.

Programmatic access

The plugin exports sendMessage and getConversation for server-side use:

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

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

// Fetch full conversation
const history = await AppKit.genie.getConversation("demo", "conversation-id");

Frontend components

The @databricks/appkit-ui package provides ready-to-use React components for Genie:

GenieChat

A full-featured chat interface that handles streaming, history, and reconnection:

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

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

The alias prop must match a key in the spaces configuration on the server.

useGenieChat hook

For custom chat UIs, use the useGenieChat hook directly:

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

See the GenieChat component reference for the full props API.