Genie Agents

データに問い合わせできるチャットボックスをユーザーに提供しましょう。text-to-SQL も、スキーマのマッピングも、独自の LLM も必要ありません。Genie Agent（旧 Genie space）は、Unity Catalog のテーブルに対する Databricks の自然言語インターフェイスです。キュレーションされたデータセット、ナレッジストア（同義語、SQL の例、列の説明）、そして質問を SQL に変換する複合 AI システムで構成されています。AppKit アプリなら、サーバー側のプラグイン 1 つとページ上のコンポーネント 1 つで組み込めます。

埋め込む前にワークスペースで Genie Agent を試すには、Genie Agent を使用するを参照してください。コーディングエージェントから作成・管理する場合は、databricks-genie-agents エージェントスキルを使用してください。

Genie ファミリーにおける Genie Agents

Genie は Databricks の製品ファミリーであり、Genie One、Genie Agents、Genie Code が含まれます。このページでは、Unity Catalog のテーブルに対する自然言語インターフェイスである Genie Agents と、それを AppKit アプリに埋め込む方法を説明します。その他の製品については、Genie の概要を参照してください。

前提条件

認証済みプロファイルを設定した Databricks CLI v1.0.0+。
稼働中の AppKit アプリ。Apps クイックスタートを参照してください。
Unity Catalog テーブル上に構成された Genie Agent。セットアップ手順は Genie Agent の作成と管理を参照してください。
アプリの設定（UI または CLI）で Can run を選択してエージェントをリソースとしてアタッチすると、Databricks がアプリのサービスプリンシパルにその権限を付与します。続いて app.yaml がそのリソースを環境変数にバインドします。エンドユーザーの権限については以下で説明します。

Genie を使う理由

質問から結果まで、Genie は次のように動作します。

Unity Catalog のテーブル、シノニム、サンプル SQL、列の説明からスキーマを理解します。
自然言語の質問から SQL を生成し、プロンプトが曖昧な場合は追加で確認を求めます。
ウェアハウスに対してクエリを実行し、そのまま描画できる表形式の結果を返します。

genie プラグインを使えば、SSE ストリーミング、認証、会話のリプレイまで面倒を見たうえで、これらすべてをチャット UI に接続できます。

プラグインを組み込む

1つ以上の space エイリアスを指定してプラグインを登録します。エイリアスのキーは、フロントエンドコンポーネントの alias プロパティになります。

server/server.ts

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

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

app.yaml で各エイリアスを Genie Agent リソースにバインドします。

app.yaml

env:
  - name: SALES_GENIE_SPACE_ID
    valueFrom: genie-space

Databricks Apps のランタイムは、リソースの space ID を環境変数に注入します。space ID は、ワークスペース内の Genie Agent ページの Settings タブで確認できます。

エージェントが 1 つだけのアプリの場合は、spaces の設定を省略し、プラグインのデフォルトの環境変数をバインドします。

app.yaml

env:
  - name: DATABRICKS_GENIE_SPACE_ID
    valueFrom: genie-space

spaces を渡さない場合、プラグインは DATABRICKS_GENIE_SPACE_ID を読み取り、default エイリアスとして登録します。

チャットコンポーネントをレンダリングする

client/src/pages/ChatPage.tsx

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

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

alias プロパティは、サーバー側の spaces 設定のキーと一致している必要があります。<GenieChat> は親要素いっぱいに広がるため、高さを固定したコンテナに配置しないと高さが 0 になってしまいます。このコンポーネントは、メッセージの描画、ストリーミングの処理、会話 ID の URL への保存、再読み込み時の履歴の復元を行います。プロパティの全一覧については GenieChat リファレンスを参照してください。

`useGenieChat` によるカスタム UI

独自のチャット UI を構築する場合は、フックを直接使用します。同じメッセージストリームに加えて、リクエストのライフサイクルを表す状態が返されます。

client/src/pages/CustomChat.tsx

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 は idle、streaming、loading-history、loading-older、error の間を遷移します。これを使って UI のローディング状態を制御してください。このフックは error、conversationId、ページネーション用のヘルパー (hasPreviousPage、isFetchingPreviousPage、fetchPreviousPage) も返します。戻り値の型の詳細は AppKit Genie プラグインリファレンスを、基盤となる REST API については Genie conversation API を参照してください。

複数のspace

space を複数登録すれば、ユーザーはドメインを切り替えて利用できます。たとえば、同じアプリ内に営業用の space とサポート用の space を用意するといったことが可能です。

server/server.ts

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

各 ID を app.yaml 内の個別のリソースにバインドします。エージェントの切り替え、会話のクリーンアップ、URL 同期に対応した実際に動作する UI については、Genie Multi-Agent Selector テンプレートを参照してください。

権限とデータアクセス

genie プラグインは、サインイン中のユーザーに代わって Genie API を呼び出します。リクエストを成功させるには、アプリのサービスプリンシパルとエンドユーザーの双方にアクセス権が必要です。

アプリのサービスプリンシパル: Genie Agent に対する CAN RUN 権限。エージェントをアプリリソースとして（UI または CLI で）アタッチし、Can run を選択すると付与されます。基盤となるデータに対する権限は自動的にはプロビジョニングされないため、Unity Catalog のテーブルに対する USE CATALOG、USE SCHEMA、SELECT をサービスプリンシパルに個別に付与してください。Add a Genie Agent resource to an app を参照してください。
エンドユーザー: Genie Agent へのアクセス権（個別またはグループ経由での共有）と、同じテーブルに対する SELECT 権限。アクセス権がないユーザーの場合、呼び出しは 403 を返します。権限チェックを自分で実装する必要はありません。

次のステップ

すぐに動く構成一式を試すには Genie Analytics App を、Knowledge Assistant や Supervisor Agent についてはカスタムエージェントの endpoint を参照してください。