> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# CopilotKit 生成式 UI

生成式 UI 是指由 Agent 协助创建、用户可与之交互的界面。CopilotKit 使用单一轴线——**生成式 UI 光谱**——来组织这些界面，范围从作者控制（每个像素都由你决定）一直延伸到 Agent 自主创建（Agent 完全掌控渲染界面）。在轴线上的位置，体现了可预测性与覆盖广度之间的取舍。

该光谱分为三个层级：

| 层级      | 界面控制者                                    | 原语                           |
| ------- | ---------------------------------------- | ---------------------------- |
| **受控式** | 组件由你编写。Agent 选择要使用的组件及传入的数据。             | Tool 调用渲染、状态渲染、推理、将组件作为 Tool |
| **声明式** | Agent 输出结构化规范。前端使用你注册的目录进行组合。            | A2UI（固定 schema 和灵活变体）        |
| **开放式** | UI 在其他位置（MCP Server）创建，并由你在 Sandbox 中运行。 | MCP Apps                     |

每个层级都由一个通过 `registerCopilotKit()` 暴露的 Mastra Agent（参阅 [CopilotKit 概览](https://mastra.zisheng.pro/guides/build-your-ui/copilotkit/overview)），以及前端中对应的 CopilotKit hook 组成。完整概念请参阅 CopilotKit 的[生成式 UI 光谱](https://www.copilotkit.ai/generative-ui-spectrum)和[生成式 UI 概览](https://docs.copilotkit.ai/concepts/generative-ui-overview)。

> **提示:** Mastra 的 [UI Dojo](https://ui-dojo.mastra.ai/) 提供可运行的 CopilotKit 示例。可浏览 `src/pages/copilot-kit` 下的源代码。

## 受控式

你提供一组固定组件，由 Agent 选择要渲染的组件并提供数据。这种方式可预测且符合品牌规范，适合高流量界面。受控式原语使用 CopilotKit v2 API，从 `@copilotkit/react-core/v2` 导入。

### Tool 调用渲染

将 Agent 的 Tool 调用渲染为 React 组件。像往常一样，在 Mastra Server 上定义 Agent 和 Tool：

```typescript
import { Agent } from '@mastra/core/agent'
import { weatherTool } from '../tools/weather-tool'

export const weatherAgent = new Agent({
  id: 'weather-agent',
  name: 'Weather Agent',
  instructions: 'Use the weatherTool to fetch current weather data.',
  model: 'openai/gpt-5.6-sol',
  tools: { weatherTool },
})
```

在前端使用 `useRenderTool`，按名称为 Tool 注册渲染器。它只负责渲染（不会执行 Tool）；`render` 函数会接收 Tool 调用的 `status`，并在 Agent 返回后接收其 `result`：

```tsx
import { z } from 'zod'
import { CopilotChat } from '@copilotkit/react-ui'
import { CopilotKit, useRenderTool } from '@copilotkit/react-core/v2'
import { Weather } from '@/components/weather'

function Chat() {
  useRenderTool(
    {
      name: 'weatherTool',
      parameters: z.object({ location: z.string() }),
      render: ({ status, result }) => {
        if (status !== 'complete') {
          return <div>Retrieving weather...</div>
        }
        return <Weather {...result} />
      },
    },
    [],
  )

  return <CopilotChat labels={{ title: 'Weather Assistant' }} />
}

export default function Page() {
  return (
    <CopilotKit runtimeUrl="http://localhost:4111/copilotkit" agent="weatherAgent">
      <Chat />
    </CopilotKit>
  )
}
```

由于 Mastra 会增量流式传输 Tool 调用参数，参数到达时会反复调用 `render` 函数，因此 UI 可以在 Agent 工作期间逐步绘制。

### 将组件作为 Tool

注册 React 组件，让 Agent 将其作为 Tool 调用。CopilotKit 会使用类型化 props（通过 Zod schema 定义）内联渲染该组件：

```tsx
import { z } from 'zod'
import { useComponent } from '@copilotkit/react-core/v2'

const schema = z.object({ text: z.string() })

function Callout({ text }: z.infer<typeof schema>) {
  return <div className="callout">{text}</div>
}

function Chat() {
  useComponent({ name: 'callout', render: Callout, parameters: schema }, [])
  return <CopilotChat labels={{ title: 'Assistant' }} />
}
```

Agent 会像调用其他 Tool 一样调用 `callout`，CopilotKit 则使用其传入的 props 渲染 `Callout`。

### 状态渲染

根据 Agent 状态渲染 UI，并在状态流式传输时重新渲染。在 Mastra 中，Agent 状态是 Agent 的工作记忆，会随着变化流式传输到客户端。使用 `useAgent` 读取状态；`agent.state` 具有响应性，因此组件会自动更新：

```tsx
import { useAgent } from '@copilotkit/react-core/v2'

function TaskBoard() {
  const { agent } = useAgent()
  const tasks = (agent.state.tasks as any[]) ?? []

  return (
    <ul>
      {tasks.map((task, i) => (
        <li key={i}>
          {task.title}: {task.status}
        </li>
      ))}
    </ul>
  )
}
```

### 推理

推理无需配置：当 Mastra Agent 运行支持推理的模型时，`CopilotChat` 会以内联方式将模型的思考过程渲染为专用消息类型，无需额外代码。如需调整样式，请将自定义组件传给 `CopilotChat` 的 `reasoningMessage` 插槽。详情请参阅 CopilotKit 的[生成式 UI 指南](https://docs.copilotkit.ai/)。

## 声明式

你不再为每个 Tool 指定固定组件，而是注册由类型化构建块组成的目录，Agent 针对每次请求将其组装成 UI 树。CopilotKit 将这种方式称为 **A2UI**（Agent-to-UI），它提供固定 schema 和灵活变体。它适合长尾的次要交互场景，在这些场景中，覆盖广度比像素级精确更重要。

最简便的方式是将目录传给 `<CopilotKit>` Provider。仅这一个 prop 就能启用 A2UI 渲染，并将 A2UI Tool 注入 Agent，因此无需修改后端：

```tsx
import { CopilotKit } from '@copilotkit/react-core/v2'
import { myCatalog } from './a2ui-catalog'

export default function Page() {
  return (
    <CopilotKit
      runtimeUrl="http://localhost:4111/copilotkit"
      agent="weatherAgent"
      a2ui={{ catalog: myCatalog }}
    >
      {/* your app */}
    </CopilotKit>
  )
}
```

目录定义原语（其 schema）和渲染器（各原语的显示方式）。在固定 schema 变体中，组件预先编写，Agent 的 Tool 只提供数据。灵活变体则让 Agent 可以更自由地组合 UI 树。请参阅 CopilotKit 的 [A2UI 文档](https://docs.copilotkit.ai/a2a/generative-ui/a2ui)。

## 开放式

在光谱的最远端，Agent 完全掌控整个界面：UI 在其他位置创建，并在你的应用中通过 Sandbox 运行。CopilotKit 通过 **MCP Apps** 支持这种方式，由 MCP Server 提供在应用内部渲染的 UI。该层级以确定性换取新颖性，是整个光谱中最具实验性的部分。

最简便的方式无需改动前端：使用现有的 `<CopilotKit>` Provider 即可。在后端，通过 `mcpApps` 选项让 `registerCopilotKit()` 指向一个或多个 MCP Server（该选项会转发给 CopilotKit Runtime）：

```typescript
registerCopilotKit({
  path: '/copilotkit',
  resourceId: 'weatherAgent',
  mcpApps: {
    servers: [{ type: 'http', url: 'http://localhost:3108/mcp', serverId: 'my-server' }],
  },
})
```

当 Agent 调用 MCP App Tool 时，CopilotKit 会在聊天中获取并渲染该 Tool 的 UI，无需额外的前端代码。请参阅 CopilotKit 的 [MCP Apps 文档](https://docs.copilotkit.ai/agno/generative-ui/mcp-apps)。

## 应用控制与交互

有些功能位于光谱之外：它们用于控制应用或为运行设置审批关卡，而不是渲染 Agent 输出。[入门指南](https://mastra.zisheng.pro/guides/build-your-ui/copilotkit/overview)中介绍了这两类功能：

- **前端 Tool**（`useFrontendTool`）：让 Agent 操作你的应用。它属于 CopilotKit 独立的[应用控制](https://docs.copilotkit.ai/)概念，其他部分还包括共享状态和 Agent 上下文。
- **人在回路**：暂停运行，等待用户批准或编辑。后端请参阅 Mastra 的 [Agent 审批](https://mastra.zisheng.pro/docs/agents/agent-approval)；前端请参阅 CopilotKit 的 [`useHumanInTheLoop`](https://docs.copilotkit.ai/reference/hooks/useHumanInTheLoop)。