生成 UI

エージェントの構造化された回答を自分の製品に表示します。

プロジェクトで Generative UI を有効にすると、回答の Markdown に openui ブロックを含められます。カード、比較、チェックリスト、グラフ、地図、タブなどに使います。通常の文章とコードは Markdown のままです。

インストール

npm install @beeuni/sdk zod @openuidev/lang-core@0.3.1
# React:
npm install react

パーサーや React レンダラーを読み込む前に、任意の依存パッケージをインストールします。SDK の主エントリーと React フックはこれらを読み込みません。

インポート先

ブロックの表示

Markdown レンダラーで genuiVersionFromClassName(className) を使います。null なら通常のコードブロックです。生成 UI のブロックが現れたときだけ、レンダラーを遅延読み込みします。

import type { ReactNode } from 'react';
import { GenuiBlock, defaultGenuiComponents } from '@beeuni/sdk/genui/react';
import { genuiVersionFromClassName } from '@beeuni/sdk/genui/fence';

type Props = {
  code: string;
  className?: string;
  streaming: boolean;
  renderMarkdown: (markdown: string) => ReactNode;
};

function StructuredReply({ code, className, streaming, renderMarkdown }: Props) {
  const version = genuiVersionFromClassName(className);
  if (version === null) return <pre><code>{code}</code></pre>;
  return (
    <GenuiBlock
      code={code}
      version={version}
      streaming={streaming}
      components={defaultGenuiComponents}
      renderMarkdown={renderMarkdown}
    />
  );
}

components に独自コンポーネントを渡すか、defaultGenuiComponents を使います。renderMarkdown の関数参照は安定させます。回答が続いていても、このブロックが閉じた時点で streaming を false にします。

未完成の大きな要素には renderPending で表示領域を確保できます。enabled={false} は Markdown を表示します。onSettled はブロックごとに結果と時間を一度通知し、内容は含めません。

テキスト表示と互換性

テキストのみの画面には genuiToMarkdown(text) を使います。グラフは表、地図は場所の一覧になり、タブや折りたたみは展開されます。ストリーミング中は { streaming: true } を渡すと、途中切れの通知を早まって出しません。

import { genuiToMarkdown } from '@beeuni/sdk/genui';

const markdown = genuiToMarkdown(reply, { streaming: true });

無効または未対応のブロックは代替表示になり、内容を実行しません。新しいブロックに対応するには SDK を更新します。チェックリストの選択はコンポーネント内だけにあり、Beeuni は保存も送信もしません。

安全性

ブロックに含まれるのはデータで、実行可能なコードではありません。リンクと画像は絶対 http または https URL が必要です。生成 UI はツールの実行やアプリの状態変更はできません。