CopilotKit 生成式 UI

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

该光谱分为三个层级：

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

每个层级都由一个通过 registerCopilotKit() 暴露的 Mastra Agent（参阅 CopilotKit 概览），以及前端中对应的 CopilotKit hook 组成。完整概念请参阅 CopilotKit 的生成式 UI 光谱和生成式 UI 概览。

提示

Mastra 的 UI Dojo 提供可运行的 CopilotKit 示例。可浏览 src/pages/copilot-kit 下的源代码。

受控式

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

Tool 调用渲染

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

src/mastra/agents/weather-agent.ts

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：

app/page.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 定义）内联渲染该组件：

app/page.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 具有响应性，因此组件会自动更新：

app/page.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 指南。

声明式

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

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

app/page.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 文档。

开放式

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

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

src/mastra/index.ts

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 文档。

应用控制与交互

有些功能位于光谱之外：它们用于控制应用或为运行设置审批关卡，而不是渲染 Agent 输出。入门指南中介绍了这两类功能：

• 前端 Tool（useFrontendTool）：让 Agent 操作你的应用。它属于 CopilotKit 独立的应用控制概念，其他部分还包括共享状态和 Agent 上下文。
• 人在回路：暂停运行，等待用户批准或编辑。后端请参阅 Mastra 的 Agent 审批；前端请参阅 CopilotKit 的 useHumanInTheLoop。