copilots

assistant-ui コパイロット

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

コパイロットは、実行中のアプリにアシスタントを接地させます。指示でアシスタントを誘導し、遅延評価されるアプリの状態を渡し、レンダリングされたコンポーネントを読み取って操作させ、インタラクタブルを通じて双方向の状態を与え、iframe の境界を越えてモデルコンテキストを共有できます。

リファレンス

• ./references/instructions.md -- useAssistantInstructions
• ./references/model-context.md -- useAssistantContext、命令型の modelContext().register、ModelContextRegistry
• ./references/visible.md -- makeAssistantVisible
• ./references/interactables.md -- アプリスコープおよびスレッドスコープのインタラクタブル、バージョン、永続化、部分更新
• ./references/assistant-frame.md -- AssistantFrameProvider と useAssistantFrameHost

オリエンテーション

すべての API は @assistant-ui/react から提供され、AssistantRuntimeProvider の内部で動作します。目的に応じて最小のツールを選んでください:

What do you need the assistant to know or do?
├─ Steer behavior with a system prompt → useAssistantInstructions("...")
├─ Feed read-only app state (page, selection, cart) → useAssistantContext({ getContext })
├─ Let it read / click / edit a rendered component → makeAssistantVisible(Component, { clickable, editable })
├─ Read AND write persistent component state via tools
│    ├─ Mounted by you, anywhere in the app → unstable_useInteractable(name, config)
│    └─ Created by the model, inline in the thread → unstable_interactableTool(config) inside defineToolkit
├─ Register instructions + tools together imperatively → aui.modelContext.register({ getModelContext })
└─ Share tools/instructions with a parent window from an embedded iframe → AssistantFrameProvider + useAssistantFrameHost

指示とコンテキストは軽量な出発点です。アシスタントが既存の DOM を認識したり操作したりする必要がある場合は makeAssistantVisible を、自動生成された update_{name} ツールを通じて変更できる構造化された双方向の状態が必要な場合はインタラクタブルを使用してください。

インタラクタブルには 2 つの世代があります。現在のものは unstable_ ファミリー（unstable_Interactables()、unstable_useInteractable、unstable_interactableTool）です。このプレフィックスは、サポートされていないという意味ではなく、変更される可能性があることを示します。レガシーファミリー（Interactables()、useAssistantInteractable、useInteractableState）は 2026-06-14 をもって非推奨となり、2026-09-14 以降に削除される予定です。この 2 つのスコープは相互に排他的です。1 つの AuiConfig にマウントできるインタラクタブル API は 1 つだけです。

import { useAssistantInstructions, useAssistantContext } from "@assistant-ui/react";

function CheckoutCopilot() {
  useAssistantInstructions("You help users complete checkout. Be concise.");
  useAssistantContext({ getContext: () => `Current page: ${window.location.href}` });
  return null;
}

getContext はモデルコンテキストが読み取られるたびに新しく評価されるため、常に現在の状態を反映します。指示とツールを同じプロバイダーから提供する必要がある場合は、命令型で登録してください:

import { useAui } from "@assistant-ui/react";
import { useEffect } from "react";

function SearchCopilot() {
  const aui = useAui();
  useEffect(() => {
    return aui.modelContext.register({
      getModelContext: () => ({
        system: "You are a helpful search assistant.",
        tools: { search: mySearchTool },
      }),
    });
  }, [aui]);
  return null;
}

register は登録解除関数を返します。これを useEffect から返すと、アンマウント時にプロバイダーがクリーンアップされます。複数のプロバイダーは合成されます。system の文字列は連結され、tools のマップはマージされます。

インタラクタブルのスコープ

config を通じてスコープを一度マウントします。アプリスコープとスレッドスコープのインタラクタブルはどちらもこれが必要です。スレッドスコープのものはさらに、そのツールキットを登録する必要があります。

import { AuiConfig, AssistantRuntimeProvider, unstable_Interactables } from "@assistant-ui/react";
import { useChatRuntime } from "@assistant-ui/ai-sdk";

function Providers({ children }: { children: React.ReactNode }) {
  const runtime = useChatRuntime();
  const config = AuiConfig({ unstable_interactables: unstable_Interactables() });

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

次に unstable_useInteractable(name, config) がインスタンスを登録し、[state, { id, setState, isPending, error, flush }] を返します。フレームワークは stateSchema の部分的なバージョンから update_{name} ツールを生成します。スレッドスコープの形式、バージョン、永続化、部分更新のマージ方法については、interactables.md を参照してください。

よくある落とし穴

アシスタントが指示やコンテキストを無視する

• フックまたは register 呼び出しは AssistantRuntimeProvider の内部で実行する必要があります。
• aui.modelContext.register は useEffect 内で呼び出し、その結果を返して購読解除されるようにしてください。レンダー中に登録するとプロバイダーがリークします。

コンテキストが古くなる

• キャプチャした値ではなく、getContext コールバック形式を使用してください。これは送信時に再読み込みされるため、最新の state を参照するクロージャは機能しますが、事前に計算した文字列は更新されません。

makeAssistantVisible が何も起こさない

• オプションなしの場合、コンポーネントは読み取り専用です（自身の outerHTML を公開します）。クリックを許可するには { clickable: true } を、<input> / <textarea> の編集を許可するには { editable: true } を渡してください。ネストされた可視コンポーネントは最外殻のみを公開します。

Interactable がレンダーごとに state をリセットする

• stateSchema と initialState はコンポーネントの外で定義してください（またはメモ化してください）。レンダーごとに新しい schema の同一性があると、interactable が再登録され、その state が消去されます。

2 つの interactables スコープが同時に登録される

• unstable_Interactables() と従来の Interactables() は相互排他的です。AuiConfig には必ず 1 つだけを保持してください。新しいコードでは unstable_Interactables() を使用します。

部分更新が期待どおりに反映されない

• プレーンなフィールドは浅くマージされます。モデルは変更されたものだけを送信し、送信したネストされたオブジェクトはそのフィールドにディープマージされるのではなく、そのフィールドを置き換えます。
• 項目が id を持つ配列フィールドは、置き換え用の配列ではなく操作（add / update / remove / clear）を受け取ります。

フレームホストがツールや指示をまったく受信しない

• 両側でメッセージのオリジンを検証します。iframe の AssistantFrameProvider.addModelContextProvider(registry, targetOrigin) と親の useAssistantFrameHost({ targetOrigin }) は、クロスオリジン埋め込みの場合、同じ明示的なオリジンを指定する必要があります。どちらかの側で targetOrigin を省略すると、そのウィンドウ自身のオリジンにデフォルト設定されます。

関連スキル

• tools -- ツールキット（defineToolkit）、バックエンドとフロントエンドのツール定義、およびカスタムツール呼び出し UI。
• runtime -- ランタイムの作成、AssistantRuntimeProvider、およびスレッド state の読み取りまたは変更（useAui、useAuiState、useAuiEvent）。