setup

assistant-ui のセットアップ

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

assistant-ui CLI は、プロジェクトの雛形生成、コンポーネントの追加、インストール状態の最新化を行います。このスキルでは、CLI を端から端まで、そして次にどのランタイムアダプターを接続するかの判断について扱います。スタイル付き UI 自体のインストールについては、elements を参照してください。

リファレンス

• ./references/ai-sdk.md -- @assistant-ui/ai-sdk (v7): トランスポート、フロントエンドツール、マルチステップ、承認、引用コンテキスト、トークン使用量、履歴、useAISDKRuntime
• ./references/ai-sdk-legacy.md -- 固定バージョンの @assistant-ui/react-ai-sdk (v6、v5) および @assistant-ui/react-data-stream (v4) のセットアップ
• ./references/langgraph.md -- @assistant-ui/react-langgraph: ストリーミング、割り込み、メッセージ編集、スレッド、エージェント状態
• ./references/langchain.md -- @assistant-ui/react-langchain: useStream ベースの LangGraph アダプター、および react-langgraph との比較
• ./references/google-adk.md -- @assistant-ui/react-google-adk: ストリーミング、ツールの確認、認証フロー、入力リクエスト、アーティファクト
• ./references/a2a.md -- @assistant-ui/react-a2a: A2AClient、タスクの状態、アーティファクト、マルチテナンシー
• ./references/ag-ui.md -- @assistant-ui/react-ag-ui: エージェント状態、割り込み、サブエージェントのネスト、カスタムイベント
• ./references/eve.md -- @assistant-ui/eve: セッション、コネクターの認可、withEve + withAui
• ./references/opencode.md -- @assistant-ui/react-opencode: 権限、質問、サブエージェントタスク、セッションの拡張機能
• ./references/claude-managed-agents.md -- useExternalStoreRuntime を介した Anthropic Managed Agents セッションの接続
• ./references/custom-backend.md -- 専用アダプターがないバックエンド向けの useLocalRuntime と useExternalStoreRuntime
• ./references/tanstack.md -- Vite + TanStack Router/Start のセットアップ
• ./references/mastra.md -- AI SDK ランタイム上での Mastra のフルスタック構成とサーバー分離構成
• ./references/cloudflare-agents.md -- @cloudflare/ai-chat と useAISDKRuntime を介した Durable Object エージェント
• ./references/providers.md -- LLM ゲートウェイ、ローカル開発向けの ChatGPT/Codex サブスクリプション、Electron
• ./references/devtools.md -- @assistant-ui/react-devtools、DevToolsModal、カスタムプラグイン

CLI の判断フロー

• 新規アプリ / 空のディレクトリ: npx assistant-ui@latest create <name>
• package.json がある既存プロジェクト: npx assistant-ui@latest init
• すでにランタイムがあるプロジェクトに 1 つ以上のスタイル付きコンポーネントを追加: npx assistant-ui@latest add <items...> (elements を参照)
• @assistant-ui/* のバージョンを更新: npx assistant-ui@latest update
• 破壊的変更を含むリリースをまたいだ移行: npx assistant-ui@latest upgrade (移行の全体像については update を参照)
• エディターをドキュメントに接続: npx assistant-ui@latest mcp
• バグ報告用の環境情報を収集: npx assistant-ui@latest info
• バージョンのずれや壊れたインストールを診断: npx assistant-ui@latest doctor
• これらのスキルをプリロードした状態で Claude Code を開く: npx assistant-ui@latest agent "add a chat sidebar"

create

npx assistant-ui@latest create my-app
npx assistant-ui@latest create my-app -t cloud-clerk
npx assistant-ui@latest create my-app -e with-langgraph
npx assistant-ui@latest create my-app --native   # Expo, equivalent to -e with-expo
npx assistant-ui@latest create my-app --ink      # React Ink, equivalent to -e with-react-ink

テンプレート (-t, --template):

テンプレート	内容
default	Vercel AI SDK、useChatRuntime
minimal	ローカルコンポーネントを使った最小構成の出発点
cloud	AssistantCloud による永続化
cloud-clerk	Clerk 認証付きの AssistantCloud 永続化
langchain	@assistant-ui/react-langchain アダプター上の LangGraph スターター
mcp	MCP ツールと MCP Apps レンダラー
eve	eve/next 上の Eve エージェント

langgraph テンプレートは存在しません。LangGraph ベースのスターターは langchain (react-langchain) であり、-e with-langgraph は生の @assistant-ui/react-langgraph アダプターをスキャフォールドします。

サンプル (-e, --example)、それぞれ完全な機能デモです:

サンプル	実演内容
with-ai-sdk-v7	Vercel AI SDK v7
with-eve	Eve エージェント統合
with-artifacts	ライブプレビュー付きの HTML アーティファクトレンダリング
with-langgraph	カスタムツールを備えた LangGraph エージェント
with-google-adk	Google ADK エージェント
with-ag-ui	AG-UI プロトコル
with-cloud	AssistantCloud 永続化
with-assistant-transport	Assistant Transport によるカスタムバックエンド
with-resumable-stream	応答の途中でリロードしても継続する再開可能なストリーム
with-chain-of-thought	推論、ツール呼び出し、ソース引用
with-external-store	外部メッセージストア
with-interactables	AI 駆動のインタラクティブ UI コンポーネント
with-openui	OpenUI 生成 UI
with-custom-thread-list	カスタムスレッドリスト UI
with-react-hook-form	React Hook Form 統合
with-ffmpeg	FFmpeg 動画処理ツール
with-elevenlabs-conversational	リアルタイム音声、ElevenLabs
with-livekit	リアルタイム音声、LiveKit
with-elevenlabs-scribe	音声文字起こし、ElevenLabs
with-expo	Expo / React Native (--native も同様)
with-react-ink	ターミナル UI チャット (--ink も同様)
with-react-router	React Router v7
with-tanstack	TanStack Start

その他のフラグ: -p, --preset <name-or-url> はスキャフォールド後に shadcn add 経由でプレイグラウンドプリセット (例: chatgpt) を適用します。--template と組み合わせられますが、--example、--native、--ink とは組み合わせられません。--use-npm / --use-pnpm / --use-yarn / --use-bun はパッケージマネージャーを固定します。--skip-install はパッケージのインストールをスキップします。--skills / --no-skills はこのリポジトリのエージェントスキルを追加またはスキップします (TTY で省略した場合は確認を求められます)。非対話シェルでは、省略された -t/-e は default テンプレートに、省略されたプロジェクトディレクトリは my-aui-app になります。

init

npx assistant-ui@latest init

package.json を持つ既存のプロジェクト向けです。プロジェクトを検出し、クイックスタートコンポーネントに対して shadcn add を実行し、デフォルトコンポーネントを追加し、TypeScript のパスを設定します。フラグ: -y, --yes は確認プロンプトをスキップします (CI やエージェントシェルで使用してください)。-o, --overwrite は既存のファイルを置き換えます。-c, --cwd <dir> はプロジェクトを選択します。--use-npm / --use-pnpm / --use-yarn / --use-bun はパッケージマネージャーを固定します。--skip-install はパッケージのインストールをスキップします。package.json なしで実行すると、代わりに create に転送されます。

add

npx assistant-ui@latest add thread thread-list

ランタイムが接続されると、add は assistant-ui レジストリ (r.assistant-ui.com) からスタイル付きコンポーネントを取得し、それらの npm 依存関係と TypeScript 型をインストールし、レジストリの依存関係を解決します (thread は markdown-text、tool-fallback、reasoning なども取得します)。-y, --yes は確認プロンプトをスキップし (デフォルトは true)、-o, --overwrite は既存のファイルを置き換え、-p, --path はインストールディレクトリを変更します。完全なカタログ、ランタイム接続 (.aui) とスタンドアロンの区分、および Radix/Base UI のスタイル対応レジストリ URL については、elements を参照してください。

インストールを最新の状態に保つ

コマンド	目的
assistant-ui update [--dry]	インストールされているすべての @assistant-ui/* パッケージを最新版に更新します。--dry は実行せずにコマンドを表示します
assistant-ui upgrade [-d] [-p] [--verbose]	現在のメジャー向けのバンドルされたすべての codemod を順番に実行します。-d はドライラン、-p は変換されたファイルを表示します
assistant-ui codemod <name> <source> [-d] [-p]	アップグレードシーケンス全体ではなく、指定した 1 つの codemod を実行します
assistant-ui mcp [--cursor|--windsurf|--vscode|--zed|--claude-code|--claude-desktop]	指定した IDE に対してホスト型 MCP ドキュメントエンドポイント（https://www.assistant-ui.com/mcp）を登録します。Zed と Claude Desktop はローカルサーバーしか起動できないため、これらの場合はローカルの @assistant-ui/mcp-docs-server stdio サーバーを登録します
assistant-ui info	CLI、OS、パッケージマネージャー、フレームワーク、インストールされている @assistant-ui/*／エコシステムのバージョンを、バグ報告にそのまま貼り付けられるブロックとして出力します
assistant-ui doctor [--no-network]	既存のインストールを診断します（@assistant-ui/* パッケージ間のバージョンのずれ、設定の誤りなど）。--no-network は最新バージョンの npm レジストリチェックをスキップします
assistant-ui agent "<prompt>" [--dry]	assistant-ui のスキルと指定したプロンプトを読み込んだ状態で Claude Code を起動します。--dry は実行せずにコマンドを表示します

現在（0.15.x）のインストールに対して codemod v0-8/ui-package-split を実行しないでください。その @assistant-ui/react-ui の移行先は現在のランタイムより前のものであり、upgrade はすでにこれを除外しています。バージョンの完全な一覧、移行の順序、および 0.15.x のフォローアップ作業（レジストリパス、AuiConfig、threads.selectionChanged）については、update を参照してください。

ランタイムを選択する

フレームワーク別、すでに適合するものがある場合：

バックエンド	フック	パッケージ	リファレンス
Vercel AI SDK v7	useChatRuntime	@assistant-ui/ai-sdk	ai-sdk.md
LangGraph Cloud（raw SDK）	useLangGraphRuntime	@assistant-ui/react-langgraph	langgraph.md
LangGraph Cloud（useStream）	useStreamRuntime	@assistant-ui/react-langchain	langchain.md
Google ADK（JS または Python）	useAdkRuntime	@assistant-ui/react-google-adk	google-adk.md
A2A v1.0 エージェントサーバー	useA2ARuntime	@assistant-ui/react-a2a	a2a.md
AG-UI エージェントサーバー	useAgUiRuntime	@assistant-ui/react-ag-ui	ag-ui.md
Eve（eve/next）	useEveAgentRuntime	@assistant-ui/eve	eve.md
OpenCode サーバー（実験的）	useOpenCodeRuntime	@assistant-ui/react-opencode	opencode.md
Claude Managed Agents セッション	useExternalStoreRuntime + useRemoteThreadListRuntime	@assistant-ui/react（専用アダプターなし）	claude-managed-agents.md

必要性別、フレームワークアダプターが適合しない場合（詳細な決定ツリーは custom-backend.md）：

必要なもの	フック	リファレンス
自分の API への fetch 呼び出し。ランタイムが状態を管理する	useLocalRuntime	custom-backend.md
メッセージがすでに redux、zustand、tanstack-query にある	useExternalStoreRuntime	custom-backend.md
バックエンドがすでにデータストリームプロトコルを出力している	useDataStreamRuntime	../streaming/SKILL.md
バックエンドが完全なエージェント状態スナップショットをストリーミングする、または双方向コマンドが必要	useAssistantTransportRuntime	../streaming/SKILL.md

フレームワークおよびプロバイダーの接続ガイド。いずれも専用アダプターではなく、上記の AI SDK ランタイムの上に構築されています：mastra.md（フルスタックまたは個別サーバー）、cloudflare-agents.md（Durable Object エージェント）、providers.md（ルーティングと BYOK 用の LLM ゲートウェイ、API キーなしでローカル開発するための ChatGPT/Codex サブスクリプション、そして Electron のホスト型バックエンドとローカルメインプロセスの分割）。

プラットフォームターゲット

ターゲット	パッケージ	スキャフォールド	スキル
Web（React）	@assistant-ui/react	create	このスキル、elements
Expo / React Native	@assistant-ui/react-native + @assistant-ui/metro	create <name> --native（または -e with-expo）	react-native
ターミナル	@assistant-ui/react-ink + @assistant-ui/react-ink-markdown	create <name> --ink（または -e with-react-ink）	ink

Vite ベースの Web アプリ（TanStack Start、素の Vite、Nuxt）は create テンプレートではありません。手動セットアップと @assistant-ui/vite の aui() コンパイラプラグインについては tanstack.md を参照してください。

よくある落とし穴

npx assistant-ui create がプロンプトなしでデフォルトテンプレートを選択する

• 標準入力が TTY ではありません（CI、エージェントのシェル）。対話式ピッカーに頼らず、-t/-e を明示的に渡してください。

「Only one scaffold selector can be provided」

• --template、--example、--native、--ink は相互排他です。--preset は --template と組み合わせられますが、他の 3 つとは組み合わせられません。

init が CI やエージェントのシェルでハングする

• -y, --yes を渡して確認プロンプトをスキップさせてください。前回の実行が残したファイルを置き換える必要がある場合は -o, --overwrite を追加します。

@assistant-ui/styles または @assistant-ui/react-ui への依存関係が解決またはインストールできない

• どちらのパッケージも廃止されています（@assistant-ui/styles は npm で非推奨とマークされています）。スタイリングは CLI がプロジェクトにコピーする要素から提供されるようになりました。依存関係を削除して npx assistant-ui@latest add thread を実行してください。

Cannot find module '@/components/assistant-ui/thread'

• コンポーネントは elements/ 配下に移動し、ランタイムに接続されるファイルには .aui サフィックスが付きます: @/components/assistant-ui/elements/thread.aui。elements を参照してください。

add がすでにカスタマイズしたコンポーネントを再インストールする

• 意図的に -o, --overwrite を渡すか、先に編集内容を別の場所へ退避してください。通常の add は既に存在するファイルをスキップします。

レジストリのインストールが create の途中で失敗する

• create はそれでもプロジェクトを完了します。レジストリまたはネットワークの問題が解消したら、表示された再試行コマンドをプロジェクトディレクトリから再実行してください。

関連スキル

• elements -- add を介してスタイル付きの Thread、ThreadList、および 120 以上のカタログコンポーネントをインストールしてカスタマイズする
• primitives -- elements の代わりに独自の UI を構成する際のスタイルなしビルディングブロック
• runtime -- 選択したランタイムのフック、アダプター、イベント、機能を詳しく解説
• update -- バージョン検出、完全な移行マップ、および upgrade の背後にある codemod の一覧
• react-native -- --native でスキャフォールドした後の Expo / React Native の詳細
• ink -- --ink でスキャフォールドした後の React Ink ターミナルの詳細
• cloud -- cloud および cloud-clerk テンプレートの背後にある AssistantCloud の永続化
• tools -- ランタイムを接続した後のツールの定義