generative-ui

assistant-ui 生成 UI

最新の API については、常に assistant-ui.com/llms.txt を参照してください。

生成 UI は、通常のツールレンダリングの関係を逆転させます。ツール呼び出しごとに 1 つのコンポーネントを手書きする代わりに、コンポーネントの語彙を提供し、そこから何かがツリーを組み立てるようにします。それはモデルが present ツールを通じて行うことも、バックエンドがメッセージパートまたは LangGraph イベントを通じて行うこともできます。@assistant-ui/generative-ui は、29 個のコンポーネント（カード、ファクト、テーブル、チャート、フォーム、コントロール）からなるデフォルトの語彙と、同じツリーを Slack Block Kit や Microsoft Teams Adaptive Card に変換するコンバーター、さらに A2UI サーフェスをそれに変換するコンバーターを提供します。そのため、一度構築したコンポジションをブラウザー内でも外でもレンダリングできます。

リファレンス

• ./references/vocabulary.md -- 29 個のデフォルトコンポーネントと、defineGenerativeComponents で独自のコンポーネントを追加する方法
• ./references/actions.md -- _action ディスパッチ、createActionRegistry、およびインタラクティブなコンポーネントが返す $input の形状
• ./references/renderers.md -- MessagePrimitive.GenerativeUI とその許可リスト、Slack および Teams コンバーター、そして 2 つの仕様形状が互換でない理由
• ./references/a2ui-openui.md -- AG-UI 上の A2UI サーフェスとサードパーティの OpenUI 統合
• ./references/tokens.md -- 共有トークン配列と、語彙を再スタイルまたは上書きする方法

どの生成 UI パターンを使うべきか？

2 つの質問がパターンを分けます。モデルがレイアウトを構成するのか、それとも事前にバインドするのか。そして、UI はツール呼び出しから生じるのか、バックエンドが出力するパートから生じるのか。

パターン	API	最適な用途
present ツール	JSONGenerativeUI + present	モデルが、提供した語彙からダッシュボード、カード、レイアウトを構成する
ツール UI	toolkit の render（tools を参照）	すでに把握している 1 つのツール呼び出しに紐づくウィジェット
生成 UI プリミティブ	MessagePrimitive.GenerativeUI + 許可リスト	すでに generative-ui メッセージパートを出力するバックエンド
LangGraph データ UI	makeAssistantDataUI + ui_message	LangGraph ストリーム上で UI を出力する LangGraph エージェント。assistant-ui.com/docs/runtimes/langgraph/generative-ui を参照
OpenUI	@openuidev/assistant-ui、サードパーティ	すでに OpenUI エコシステムとそのコンポーネントキットに投資している場合

最初の 2 つはツール駆動であるため、UI がいつ表示されるかはモデルが決めます。LangGraph の行はバックエンド駆動であるため、UI がいつ表示されるかはエージェントが決めます。present と生成 UI プリミティブはどちらも JSON コンポーネントツリーを受け取りますが、互換性のない形状です。詳しくは 仕様形状の違い を参照してください。present 用に構築されたツリーは、Slack および Teams コンバーターが受け入れ、A2UI コンバーターが生成する形状でもあります。

クイックスタート

パッケージをインストールし、スタイル付き要素を追加して、お使いのフレームワーク向けの "use generative" コンパイラを有効にします。

zod は /react エントリーがインポートするオプションの peer 依存関係であるため、パッケージと一緒にインストールしてください。

npm install @assistant-ui/generative-ui zod
npx assistant-ui@latest add generative-ui

import { withAui } from "@assistant-ui/next";

export default withAui({
  /* your Next config */
});

Vite と TanStack Start は @assistant-ui/vite の aui() を使用します（plugins: [aui({ ... })]）。Expo と bare React Native は metro.config.js 内で const { withAui } = require("@assistant-ui/metro"); を使用します。このディレクティブにより、1 つのファイルでブラウザーとサーバールートの両方がインポートするツールを宣言できます。コンパイラはサーバービルドからブラウザー専用の部分を、クライアントビルドからスキーマを除去します。

JSONGenerativeUI はコンポーネントライブラリを present 向けのモデル対向スキーマに変換します。結果は他のツールと同様にツールキットに登録します。

"use generative";

import { defineToolkit } from "@assistant-ui/react";
import {
  JSONGenerativeUI,
  defaultGenerativeUILibrary,
} from "@assistant-ui/generative-ui/react";

const generative = new JSONGenerativeUI({
  library: defaultGenerativeUILibrary,
});

export default defineToolkit({
  present: generative.present({ display: "standalone" }),
});

display: "standalone" は結果を思考の連鎖のトレースの外側にある専用のサーフェスに描画します。省略するとインラインで描画されます。デフォルトのボキャブラリーは独自のコンポーネントなしですでに動作する構成です。完全なリストと拡張方法については vocabulary.md を参照してください。

AuiConfig を介してクライアントにツールキットを登録し、フロントエンドツールが解決したら実行が継続するように sendAutomaticallyWhen を設定します。

"use client";

import { AssistantRuntimeProvider, AuiConfig, Tools } from "@assistant-ui/react";
import { useChatRuntime } from "@assistant-ui/ai-sdk";
import { lastAssistantMessageIsCompleteWithToolCalls } from "ai";
import toolkit from "./toolkit";

export function MyRuntimeProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  const runtime = useChatRuntime({
    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
  });
  const config = AuiConfig({ tools: Tools({ toolkit }) });

  return (
    <AssistantRuntimeProvider runtime={runtime} config={config}>
      {children}
    </AssistantRuntimeProvider>
  );
}

present はフロントエンドツールです。ブラウザーで解決され、sendAutomaticallyWhen がない場合、UI が描画されてからモデルが何か言う前に会話が停止します。

ルートは同じツールキットモジュールをインポートします。コンパイラはそのインポートをサーバービルドに解決するため、スキーマだけが受け渡され、ブラウザーコードがサーバーバンドルに入ることはありません。

import { openai } from "@ai-sdk/openai";
import { AISDKToolkit } from "@assistant-ui/ai-sdk";
import { convertToModelMessages, stepCountIs, streamText } from "ai";
import toolkit from "@/app/toolkit";

const aiToolkit = new AISDKToolkit({ toolkit });

export async function POST(req: Request) {
  const { messages, tools } = await req.json();

  const result = streamText({
    model: openai("gpt-5.6-luna"),
    messages: await convertToModelMessages(messages),
    stopWhen: stepCountIs(10),
    tools: await aiToolkit.tools({ frontend: tools }),
  });

  return result.toUIMessageStreamResponse();
}

ツールキットモジュールをインポートするバックエンドが存在しない場合、たとえばクラウドホスト型の実行では、backendless: true でコンパイルするとクライアントが present のものを含むすべてのアップロード可能なスキーマを保持します。

export default withAui({ ...yourConfig, aui: { backendless: true } });

スタイルを適用する

上で実行した npx assistant-ui@latest add generative-ui は、同梱のスタイルシートと components/assistant-ui/elements/generative-ui.tsx をインストールします。後者は styledGenerativeUILibrary をエクスポートします。これは同じ 29 個のコンポーネントで、デフォルトのプレーンテキストのものと入れ替えて実際の markdown レンダラーを使用します。これは "use client" モジュールであるため、"use generative" ツールキットファイルへの組み込みは以下の注意点にあるクライアントモジュールのルールに従います。正確なオーバーライドパターン、data-aui スタイリングフック、トークン配列については tokens.md を参照してください。

present 以外の用途

• 独自のコンポーネントでボキャブラリーを拡張する、または表示用にモデルが生成したツリーを読み戻す: vocabulary.md。
• _action を介して描画されたノードからアプリにコールバックさせる: actions.md。
• バックエンドがすでに出力している generative-ui メッセージパートを、MessagePrimitive.GenerativeUI と利用側が提供する許可リストで描画する: renderers.md。
• ツリーを Slack や Microsoft Teams に投稿する、AG-UI 上で A2UI サーフェスを描画する、またはサードパーティの OpenUI 連携を組み込む: renderers.md と a2ui-openui.md。

よくある落とし穴

present が UI をレンダリングしたあと、会話がそのまま止まる

• present はフロントエンドのツールです。useChatRuntime に sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls を指定しないと、解決後に実行が続行されません。

クラウドホスト型バックエンドでは、モデルが present を認識しない

• クライアントビルドは、あなたのバックエンドが同じツールキットモジュールをインポートしていると想定するため、フロントエンドと human のスキーマのアップロードを省略します。あなたのサーバーがどれもこれを行わない場合は、aui: { backendless: true } でコンパイルしてください。

styledGenerativeUILibrary が "use generative" ビルドを壊す

• これは "use client" モジュールです。"use generative" ファイルから参照できるのは、defineGenerativeComponents 呼び出し内のインライン render 値としてのみで、スプレッド、トップレベルの定数、あるいは library オプションとして直接渡すことはできません。library に直接渡す方法が機能するのは、"use generative" ディレクティブのない通常のファイル内だけです。詳しくは tokens.md を参照してください。

generative-ui メッセージパーツが何もレンダリングしない

• デフォルトの shadcn Thread は MessagePrimitive.GenerativeUI を接続していません。メッセージレンダラーで明示的にオプトインしてください。詳しくは renderers.md を参照してください。

不明なコンポーネント名：黙って破棄される場合とエラーがスローされる場合

• present ツールの経路では、認識されない _type は破棄され、開発時に警告が出ます。 generative UI プリミティブは、Fallback を渡さない限り型付きの GenerativeUIRenderError をスローします。どちらの境界も、それらのコンポーネントが受け取る props を制約しません。href/src の値はご自身で検証し、エージェントが指定した props を dangerouslySetInnerHTML に決して転送しないでください。

Slack や Teams の出力がブラウザと一致しない

• 変換は完全ですが不可逆です。返される warnings 配列を確認してください。変換されるのは present 用に構築された $type ツリーのみです。プリミティブの { component, props } 形式には Slack、Teams、A2UI のコンバーターがありません。

useChatRuntime はネイティブの generative-ui パーツを決して出力しない

• AI SDK はツール結果を generative-ui パーツではなく tool-call パーツにマッピングします。結果をご自身でスペックにパースする render_gui ツールで橋渡ししてください（ドキュメントではそのヘルパーを parseRenderGuiResult と呼んでいますが、これはパッケージのエクスポートではありません）。詳しくは renderers.md を参照してください。

関連スキル

• tools -- ツールキットの作成、"use generative" コンパイラー、および特定のツール呼び出しに紐づくウィジェット向けのツール UI
• elements -- generative-ui スタイル要素とカタログの残りのインストール
• primitives -- MessagePrimitive とその他のスタイルなしビルディングブロック
• runtime -- AuiConfig、Tools、および設定関連の残りの部分