CopilotKit 生成式 UI

生成式 UI 是指由 Agent 協助建立、讓用戶可以互動的介面。CopilotKit 將這些介面編排在單一軸線上，稱為生成式 UI 光譜；它從由開發者控制（每個像素都由你決定），一路延伸至由 Agent 自行創建（呈現的介面完全由 Agent 掌控）。你在軸線上選擇的位置，就是可預測性與涵蓋範圍之間的取捨。

此光譜分為三個層級：

層級	由誰控制介面	基本機制
受控	組件由你編寫。Agent 選擇要使用哪個組件，以及要傳入甚麼資料。	Tool 呼叫呈現、狀態呈現、推理、將組件用作 Tool
聲明式	Agent 輸出結構化規格。前端使用你已註冊的目錄來組合介面。	A2UI（固定結構及彈性變體）
開放式	UI 在其他地方（MCP 伺服器）創建，而你將它置於 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 伺服器上定義 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 則使用 Agent 傳入的 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 slot。詳情請參閱 CopilotKit 的生成式 UI 指南。

聲明式

你毋須為每個 Tool 設定固定組件，而是註冊一套具備類型的基本構件目錄，再由 Agent 按每項請求將它們組合成 UI 樹。CopilotKit 將這種方式稱為 A2UI（Agent-to-UI），並提供固定結構及彈性兩種變體。它適合像素精準度不及涵蓋範圍重要的各種次要互動。

最簡單直接的做法，是將你的目錄傳入 <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）及呈現器（每個基本構件的顯示方式）。在固定結構變體中，組件會預先編寫，而 Agent 的 Tool 只會提供資料。彈性變體則讓 Agent 更自由地組合 UI 樹。請參閱 CopilotKit 的 A2UI 文件。

開放式

在光譜的最遠端，Agent 掌控整個介面：UI 在其他地方創建，並置於你應用程式的 Sandbox 內。CopilotKit 透過 MCP Apps 支援這種方式，由 MCP 伺服器提供 UI，並在你的應用程式內呈現。此層級以確定性換取新穎性，也是光譜上最具實驗性的一點。

最簡單直接的做法可讓前端維持不變：現有的 <CopilotKit> Provider 已經足夠。在後端，使用 mcpApps 選項，將 registerCopilotKit() 指向一個或多個 MCP 伺服器（此選項會轉交至 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 另一個獨立的 App Control 概念，並包括共享狀態及 Agent context。
• Human-in-the-loop：暫停執行流程，等待用戶批准或修改。後端方面，請參閱 Mastra 的 Agent 批准機制；前端方面，請參閱 CopilotKit 的 useHumanInTheLoop。