update

assistant-ui のアップデート

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

アップグレードは 2 段階で行います。まず AI SDK とその assistant-ui アダプターを互換にし、その後 assistant-ui を更新して API マイグレーションを適用します。直接一気に移行すると複数の非推奨期間をまたぐ可能性があるため、編集前に該当するリファレンスを読んでください。

リファレンス

• ./references/ai-sdk.md -- AI SDK v4 および v5 から v6 へのマイグレーション、v6 から v7 への変更、アダプターの固定
• ./references/assistant-ui.md -- assistant-ui 0.8 から 0.15 まで、ツールキット、LangGraph、非推奨ポリシー
• ./references/breaking-changes.md -- バージョンと症状のクイック検索

インストールされている系統を検出する

これらのコマンドはアプリケーションのルートから実行します。npm ls はインストールされている依存関係グラフを報告し、npm view は公開されている最新バージョンを報告します。

npm ls @assistant-ui/react @assistant-ui/ai-sdk @assistant-ui/react-ai-sdk @assistant-ui/core @assistant-ui/store assistant-stream ai @ai-sdk/react

npm view @assistant-ui/react version
npm view @assistant-ui/ai-sdk version
npm view @assistant-ui/react-ai-sdk version
npm view @assistant-ui/core version
npm view @assistant-ui/store version
npm view assistant-stream version
npm view ai version
npm view @ai-sdk/react version

2026 年 9 月時点で公開されている系統:

パッケージ	現在の系統
assistant-ui	0.0.x
@assistant-ui/react	0.15.x
@assistant-ui/ai-sdk	0.0.x
@assistant-ui/react-ai-sdk	1.4.x
@assistant-ui/core	0.3.x
@assistant-ui/store	0.3.x
assistant-stream	0.3.x
assistant-cloud	0.1.x
ai	7.x

@assistant-ui/react-ai-sdk は古いインストール向けに同じ API を再エクスポートします。新しいコードでは @assistant-ui/ai-sdk からインポートします。

マイグレーションセットを選択する

インストールされている @assistant-ui/react のバージョンを、以下のすべてのしきい値と比較します。該当するすべてのガイドをバージョンの昇順で適用します。

インストールされているバージョン	確認する項目
0.8.x	過去の UI パッケージ分割。現在のアップグレードバンドルには v0-8/ui-package-split が意図的に含まれていません。その移行先が現在のランタイムと互換性がないためです。Elements レジストリへ手動で移行してください。
0.9.x	v0-9/edge-package-split codemod。
0.10.x	バンドルされているマイグレーションには 0.10 専用の codemod はありません。以降の codemod を実行し、プロジェクトの現在のツールチェーンで残ったパッケージまたはビルドのエラーを解決してください。
0.11.x	ContentPart の名前と MessagePrimitive.Content が MessagePart と MessagePrimitive.Parts になります。
0.12.x	統一された state API、フックのエイリアス、camelCase のイベント名。
0.13.x	先に進む前に 0.14 のガイドを確認してください。v0.11 と v0.12 の非推奨が削除されるためです。
0.14.x	削除されたエイリアスとランタイム API、およびプリミティブの children レンダー関数。
0.15.x	スコーププロパティ、削除されたレガシーフック、toolUIs、standalone-tool-call、AuiConfig、threads.selectionChanged。

マイグレーションの順序

1. まず AI SDK をマイグレーションします。プロジェクトが v4、v5、v6 の場合は ai-sdk.md を読んでください。@assistant-ui/ai-sdk とともに ai@^7 および @ai-sdk/react@^4 を対象とします。
2. 次に assistant-ui を更新します。しきい値の表と assistant-ui.md を使用し、該当する最も古いバージョンから始めます。
3. 検証はパッケージとソースのマイグレーションが両方完了した後にのみ行います。型チェック、ビルド、およびアプリケーションが使用するチャット、ツール、承認、スレッド選択のパスを実行します。

CLI を実行する

# Update every installed @assistant-ui/* package.
npx assistant-ui@latest update

# Preview package changes without installing them.
npx assistant-ui@latest update --dry

# Preview the complete bundled migration and print each transformed file.
npx assistant-ui@latest upgrade -d -p

# Apply one codemod to a source directory.
npx assistant-ui@latest codemod v0-11/content-part-to-message-part ./src

# Report environment and dependency details.
npx assistant-ui@latest doctor
npx assistant-ui@latest info

バンドルされているアップグレードコマンドは、これらの codemod を次の正確な順序で実行します:

1. v0-9/edge-package-split
2. v0-11/content-part-to-message-part
3. v0-12/assistant-api-to-aui
4. v0-12/event-names-to-camelcase
5. v0-12/primitive-if-to-aui-if
6. v0-15/aui-accessor-calls-to-properties

まず dry および print の形式を使用します。差分を確認した後、-d と -p を付けずに upgrade を実行します。現在のアップグレードに過去の v0-8/ui-package-split codemod を追加しないでください。

0.15.x のフォローアップ

これらの変更は、別のメジャーを伴わずに 0.15.0 の後にリリースされました。プロジェクトがすでに 0.15.x を宣言している場合でも、これらを洗い出してください。

AI SDK のインポートを移動する

// Before
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

// After
import { useChatRuntime } from "@assistant-ui/ai-sdk";

クライアント構築を設定に置き換える

useAui は設定を一切受け取りません。AuiConfig で設定を構築し、それをプロバイダーに渡します。ネストされた AuiProvider は、親クライアントを拡張するのか、それとも分離されているのかを宣言する必要があります。

// Before
const aui = useAui({ tools: Tools({ toolkit }) });
return <AuiProvider value={aui}>{children}</AuiProvider>;

// After
const aui = useAui();
const config = AuiConfig({ tools: Tools({ toolkit }) });
return <AuiProvider extends={aui} config={config}>{children}</AuiProvider>;

実行時の境界では、AssistantRuntimeProvider の aui を config に置き換えます。分離されたルートには、AuiProvider extends={null} config={config} を使用します。

// Before
return <AssistantRuntimeProvider runtime={runtime} aui={aui}>{children}</AssistantRuntimeProvider>;

// After
const config = AuiConfig({ tools: Tools({ toolkit }) });
return <AssistantRuntimeProvider runtime={runtime} config={config}>{children}</AssistantRuntimeProvider>;

コピーされたレジストリコンポーネントを移動する

実行時に接続されるレジストリコンポーネントは components/assistant-ui/elements/.aui.tsx に配置し、@/components/assistant-ui/elements/.aui としてインポートします。レンダラーとスタンドアロンの Elements は components/assistant-ui/elements/.tsx を使用し、インポートから .aui を省略します。廃止された @/components/assistant-ui/ のインポートも、同じ一括作業の中で置き換えてください。

スレッド選択イベントを統合する

// Before
useAuiEvent("threadListItem.switchedTo", ({ threadId }) => select(threadId));
useAuiEvent("threadListItem.switchedAway", ({ threadId }) => clear(threadId));

// After
useAuiEvent("threads.selectionChanged", ({ threadId, previousThreadId }) => {
  select(threadId);
  if (previousThreadId) clear(previousThreadId);
});

新しいイベントは threads スコープで共有されます。以前は thread-list アイテムの内部にあったリスナーは、そのアイテム id でフィルタリングできます。

レガシーの interactables とツール登録を置き換える

useAssistantInteractable、Interactables()、useInteractableState は 2026-06-14 以降非推奨であり、2026-09-14 以降に削除される予定です。unstable_useInteractable、unstable_Interactables()、unstable_interactableTool に移行してください。

makeAssistantTool、useAssistantTool、makeAssistantToolUI、useAssistantToolUI は非推奨です。モデル契約、エグゼキューター、レンダラーを defineToolkit エントリにまとめ、AuiConfig({ tools: Tools({ toolkit }) }) で登録します。ステートフルなツールや UI 専用のツールを変換する前に、assistant-ui.md のツールキットのセクションをお読みください。

検証

npx tsc --noEmit
npm run build
npm test

また、実際のチャットルートを開き、通常のメッセージ、ツール呼び出し、存在する場合は承認ゲート、スレッドの切り替え、プロジェクトの永続化された履歴のパスを検証してください。依存関係や環境の不一致が残る場合は、npx assistant-ui@latest doctor と npx assistant-ui@latest info を実行してください。

よくある落とし穴

アップグレードコマンドでインポートは変わったが、アプリがまだ古いアダプターを使用している

• パッケージの更新は @assistant-ui パッケージのみを対象としています。ai と @ai-sdk/react を別途更新し、その後 AI SDK のリファレンスに従ってください。
• @assistant-ui/react-ai-sdk は古いインストール向けのエイリアスです。現在のソースは @assistant-ui/ai-sdk からインポートします。

AuiProvider または AssistantRuntimeProvider が古い props を受け付けなくなった

• useAui() はコンテキストへのアクセスのみです。AuiConfig({...}) を構築し、config として渡してください。
• ネストされた AuiProvider には extends={aui} が必要です。分離されたものには extends={null} が必要です。

スコープの参照が null チェックのように動作しなくなった

• aui.thread は常に truthy です。オプションのスコープにアクセスする前に aui.thread.source != null を確認してください。
• スコープのアクセサーはプロパティです。スコープ自体ではなく、スコープのメソッドを呼び出してください。

型チェックで削除されたフックやツールマップがまだ検出される

• assistant-ui.md の削除されたフックの完全なマッピングを適用してください。
• s.tools.tools を s.tools.toolUIs に、mcp-app グループキーを standalone-tool-call に置き換えてください。

関連スキル

• setup -- これまで使用したことのないプロジェクトに assistant-ui をインストールします
• runtime -- 移行後にアクティブなランタイムを構築またはカスタマイズします
• tools -- ツールキット、フロントエンドツール、承認、ツール UI を作成します
• elements -- コピーされた Elements レジストリコンポーネントをインストールしてカスタマイズします