# 生成 UI

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

Canonical page: https://beeuni.ai/docs/ja/sdk/genui

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

## インストール

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

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

## インポート先

| Import | API |
| --- | --- |
| `@beeuni/sdk/genui/fence` | 追加の依存なしでブロックを検出 |
| `@beeuni/sdk/genui` | パーサー、カタログ、Markdown 変換 |
| `@beeuni/sdk/genui/react` | デザインを固定しない React レンダラーと標準 HTML コンポーネント |

## ブロックの表示

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

```tsx
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 }` を渡すと、途中切れの通知を早まって出しません。

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

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

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

## 安全性

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