CopilotKit 생성 UI

생성적 UI는 Agent가 생성을 돕고 사용자가 상호 작용할 수 있는 인터페이스를 설명합니다. CopilotKit은 단일 축을 따라 이러한 인터페이스를 구성합니다.generative UI spectrum, 작성자 제어(모든 픽셀 결정)에서 Agent 발명(Agent가 렌더링된 표면을 소유함)까지 실행됩니다. 축에서 귀하의 위치는 예측 가능성과 폭 사이의 절충안입니다.

스펙트럼에는 세 가지 계층이 있습니다.

계층	표면을 통제하는 사람	프리미티브
Controlled	컴포넌트는 사용자가 작성합니다. Agent는 사용할 컴포넌트와 전달할 데이터를 선택합니다.	Tool 호출 렌더링, 상태 렌더링, 추론, Tool로서의 컴포넌트
Declarative	Agent가 구조화된 사양을 내보냅니다. 프런트엔드는 사용자가 등록한 카탈로그를 사용해 이를 구성합니다.	A2UI(고정 스키마 및 유연한 변형)
개방형	UI는 다른 곳(MCP 서버)에서 개발되었으며 이를 샌드박스에 넣습니다.	MCP 앱

각 계층은 다음을 통해 노출되는 Mastra Agent입니다.registerCopilotKit() (see CopilotKit overview)와 프런트엔드의 해당 CopilotKit hook을 함께 사용합니다. 전체 개념은 CopilotKit의 generative UI spectrum and generative UI overview.

팁

마스트라의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 },
})

프런트엔드에서 Tool에 대한 렌더러를 이름으로 등록합니다.useRenderTool. 이는 렌더링 전용이며 Tool을 실행하지 않습니다. render function receives the tool call's status and, once the agent returns, its 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 함수는 인수가 도착할 때마다 반복해서 호출되므로 Agent가 작업하는 동안 UI를 점진적으로 렌더링할 수 있습니다.

Tool로서의 구성 요소

React 구성 요소를 등록하고 Agent가 이를 Tool로 호출하도록 합니다. CopilotKit은 입력된 소품(Zod 스키마로 정의됨)을 사용하여 인라인으로 렌더링합니다.

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가 호출합니다.callout like any other tool, and CopilotKit renders Callout with the props it passed.

상태 렌더링

Agent 상태에서 UI를 렌더링하고 스트리밍할 때 다시 렌더링합니다. Mastra에서 Agent 상태는 Agent의 작업 Memory이며 변경 시 클라이언트로 스트리밍됩니다. 함께 읽어보세요useAgent; agent.state is reactive, so the component updates automatically:

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가 추론 가능 Model을 실행할 때CopilotChat 는 Model의 사고 과정을 별도의 메시지 유형으로 인라인 렌더링하며 추가 코드가 필요하지 않습니다. 스타일을 변경하려면 자체 컴포넌트를 reasoningMessage slot on CopilotChat. See CopilotKit's generative UI guides for details.

선언적

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>
  )
}

카탈로그는 기본 요소(해당 스키마)와 렌더러(각 기본 요소가 표시되는 방식)를 정의합니다. 고정 스키마 변형에서는 구성 요소가 미리 작성되고 Agent Tool은 데이터만 제공합니다. 유연한 변형을 사용하면 Agent가 트리를 더 자유롭게 구성할 수 있습니다. CopilotKit 보기A2UI documentation.

개방형

스펙트럼의 맨 끝에 있는 Agent는 전체 표면을 소유합니다. UI는 다른 곳에서 개발되고 앱에서 샌드박스 처리됩니다. CopilotKit은 다음을 통해 이를 지원합니다.MCP Apps. 여기서는 MCP 서버가 애플리케이션 내부에 렌더링되는 UI를 제공합니다. 이 계층은 결정성을 낮추는 대신 참신성을 높이며, 전체 스펙트럼에서 가장 실험적인 지점에 해당합니다.

저항이 가장 적은 경로는 프런트엔드를 그대로 유지합니다. 즉, 기존<CopilotKit> provider is enough. On the backend, point registerCopilotKit() at one or more MCP servers with the mcpApps option (it's forwarded to the 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 앱 Tool을 호출하면 CopilotKit은 추가 프런트엔드 코드 없이 채팅에서 해당 Tool의 UI를 가져와 렌더링합니다. CopilotKit 보기MCP Apps documentation.

앱 제어 및 상호작용

일부 기능은 스펙트럼 위가 아닌 옆에 위치합니다. Agent 출력을 렌더링하는 대신 앱을 제어하거나 실행을 제어합니다. 둘 다 포함되어 있습니다.Get started:

• 프런트엔드 Tool (useFrontendTool): Agent가 애플리케이션에서 작업을 수행하도록 합니다. 이는 CopilotKit의 별도 App Control concept, alongside shared state and agent context.
• 인간 참여형: 실행을 일시 중지하고 사용자 승인이나 편집을 기다립니다. 백엔드 측면, Mastra 참조Agent approval; frontend side, see CopilotKit's useHumanInTheLoop.