copilots

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

assistant-ui Copilots

Always consult assistant-ui.com/llms.txt for the latest API.

Copilots ground an assistant in your running app: steer it with instructions, feed it lazy app state, let it read rendered components, click and edit UI, and read or update persistent interactable state.

请务必查阅assistant-ui.com/llms.txt获取最新API。

Copilots可将助手集成到你的运行中应用：通过指令引导其行为、为其提供懒加载应用状态、允许它读取渲染组件、点击和编辑UI，以及读取或更新持久化交互状态。

References

参考资料

./references/instructions.md -- useAssistantInstructions
./references/model-context.md -- useAssistantContext and imperative modelContext().register
./references/visible.md -- makeAssistantVisible
./references/interactables.md -- interactable components

./references/instructions.md -- useAssistantInstructions
./references/model-context.md -- useAssistantContext 和命令式 modelContext().register
./references/visible.md -- makeAssistantVisible
./references/interactables.md -- 交互组件

Orientation

指南

All APIs ship from

@assistant-ui/react

and run inside

AssistantRuntimeProvider

. Pick the smallest tool for the job:

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 → useAssistantInteractable(name, config)
└─ Register instructions + tools together imperatively → useAui().modelContext().register({ getModelContext })

Instructions and context are the lightweight starting point. Reach for

makeAssistantVisible

when the assistant needs to perceive or drive existing DOM, and for interactables when it needs structured two-way state it can mutate through auto-generated

update_{name}

tools.

tsx

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

is evaluated fresh each time the model context is read, so it always reflects current state. Register imperatively when you need instructions and tools in one provider:

tsx

import { useAui, tool } 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

returns an unsubscribe function; returning it from

useEffect

cleans up the provider on unmount. Multiple providers compose:

system

strings concatenate and

tools

maps merge.

所有API均来自

@assistant-ui/react

，并在

AssistantRuntimeProvider

内部运行。按需选择最适合的工具：

你需要助手了解或执行什么操作？
├─ 用系统提示引导行为 → useAssistantInstructions("...")
├─ 提供只读应用状态（页面、选中内容、购物车）→ useAssistantContext({ getContext })
├─ 允许它读取/点击/编辑渲染组件 → makeAssistantVisible(Component, { clickable, editable })
├─ 通过工具读取并写入持久化组件状态 → useAssistantInteractable(name, config)
└─ 命令式注册指令+工具 → useAui().modelContext().register({ getModelContext })

指令和上下文是轻量级的入门方案。当助手需要感知或驱动现有DOM时，使用

makeAssistantVisible

；当它需要可通过自动生成的

update_{name}

工具修改的结构化双向状态时，使用交互组件。

tsx

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

function CheckoutCopilot() {
  useAssistantInstructions("你帮助用户完成结账流程。请保持简洁。");
  useAssistantContext({ getContext: () => `当前页面：${window.location.href}` });
  return null;
}

每次读取模型上下文时都会重新计算

getContext

，因此它始终反映当前状态。当你需要在一个提供者中同时注册指令和工具时，可使用命令式注册：

tsx

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

function SearchCopilot() {
  const aui = useAui();
  useEffect(() => {
    return aui.modelContext().register({
      getModelContext: () => ({
        system: "你是一个乐于助人的搜索助手。",
        tools: { search: mySearchTool },
      }),
    });
  }, [aui]);
  return null;
}

register

会返回一个取消订阅函数；在

useEffect

中返回该函数可在组件卸载时清理提供者。多个提供者可组合：

system

字符串会拼接，

tools

映射会合并。

Common Gotchas

常见问题

Assistant ignores instructions or context

The hook or
```
register
```
call must run inside
```
AssistantRuntimeProvider
```
.
For
```
useAui().modelContext().register
```
, call it in
```
useEffect
```
and return the result so it unsubscribes; registering in render leaks providers.

Context is stale

Use the
```
getContext
```
callback form, not a captured value. It is re-read at send time, so closures over fresh state work; a precomputed string will not update.

makeAssistantVisible does nothing

Without options the component is read-only (exposes its
```
outerHTML
```
). Pass
```
{ clickable: true }
```
to allow clicks and
```
{ editable: true }
```
for
```
<input>
```
/
```
<textarea>
```
editing. Nested visible components expose only the outermost.

Interactable resets its state on every render

Define
```
stateSchema
```
and
```
initialState
```
outside the component (or memoize). A new schema each render re-registers the interactable and wipes its state. Register the scope with
```
useAui({ interactables: Interactables() })
```
.

Partial updates drop fields

The AI sends only the fields it changes and the merge is shallow (one level deep); nested objects are replaced, not deep-merged.

助手忽略指令或上下文

Hook或
```
register
```
调用必须在
```
AssistantRuntimeProvider
```
内部运行。
对于
```
useAui().modelContext().register
```
，请在
```
useEffect
```
中调用并返回结果以取消订阅；在渲染阶段注册会导致提供者泄漏。

上下文过时

使用
```
getContext
```
回调形式，而非捕获的值。发送时会重新读取它，因此闭包中的最新状态会生效；预计算的字符串不会更新。

makeAssistantVisible无效果

若无选项，组件为只读（暴露其
```
outerHTML
```
）。传递
```
{ clickable: true }
```
以允许点击，传递
```
{ editable: true }
```
以支持
```
<input>
```
/
```
<textarea>
```
编辑。嵌套的可见组件仅暴露最外层。

交互组件在每次渲染时重置状态

在组件外部定义
```
stateSchema
```
和
```
initialState
```
（或进行memoize处理）。每次渲染时新的schema会重新注册交互组件并清除其状态。通过
```
useAui({ interactables: Interactables() })
```
注册作用域。

部分更新丢失字段

AI仅发送它修改的字段，且合并是浅层次的（仅一级深度）；嵌套对象会被替换，而非深度合并。

copilots

Original

Translation

assistant-ui Copilots

assistant-ui Copilots

References

参考资料

Orientation

指南

Common Gotchas

常见问题

Related Skills

相关技能