copilots

assistant-ui 副驾驶

请始终查阅 assistant-ui.com/llms.txt，以获取最新 API。

副驾驶可让助手以正在运行的应用为依据：通过指令引导它，为它提供延迟加载的应用状态，让它读取并操控已渲染的组件，通过可交互项提供双向状态，并跨 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} 工具进行修改的结构化双向状态时，则使用可交互项。

可交互项有两代 API。当前版本是 unstable_ 系列（unstable_Interactables()、unstable_useInteractable、unstable_interactableTool）；此前缀表示 API 可能发生变化，而不是不受支持。旧版系列（Interactables()、useAssistantInteractable、useInteractableState）自 2026-06-14 起已弃用，计划于 2026-09-14 或之后移除。两个作用域互斥：在一个 AuiConfig 中只能挂载一种可交互项 API。

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。

常见问题

助手忽略指令或上下文

• Hook 或 register 调用必须在 AssistantRuntimeProvider 内运行。
• 对于 aui.modelContext.register，请在 useEffect 中调用并返回其结果，以便取消订阅；在渲染期间注册会导致提供程序泄漏。

上下文已过时

• 使用 getContext 回调形式，而不是捕获一个值。它会在发送时重新读取，因此闭包可以使用最新状态；预先计算的字符串则不会更新。

makeAssistantVisible 不起作用

• 不传选项时，组件为只读（会公开其 outerHTML）。传入 { clickable: true } 以允许点击，并传入 { editable: true } 以允许编辑 <input> / <textarea>。嵌套的可见组件只会公开最外层组件。

Interactable 每次渲染都会重置其状态

• 在组件外定义 stateSchema 和 initialState（或对它们进行记忆化）。每次渲染时 schema 的标识都改变，会导致重新注册 interactable 并清除其状态。

同时注册了两个 interactables 作用域

• unstable_Interactables() 和旧版 Interactables() 不能同时使用。在 AuiConfig 中只能保留一个；新代码使用 unstable_Interactables()。

部分更新未按预期生效

• 普通字段会进行浅层合并：模型只发送发生变化的内容，而它发送的嵌套对象会替换该字段，而不是与其进行深度合并。
• 项目带有 id 的数组字段会使用操作（add / update / remove / clear），而不是替换整个数组。

Frame 宿主始终收不到工具或指令

• 两侧都会验证消息来源。对于跨域嵌入，iframe 的 AssistantFrameProvider.addModelContextProvider(registry, targetOrigin) 和父级的 useAssistantFrameHost({ targetOrigin }) 必须指定相同的明确来源；任一侧省略 targetOrigin 时，都会默认使用该窗口自身的来源。

相关技能

• 工具 -- 工具包（defineToolkit）、后端和前端工具定义，以及自定义工具调用 UI。
• 运行时 -- 运行时创建、AssistantRuntimeProvider，以及读取或修改线程状态（useAui、useAuiState、useAuiEvent）。