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

# OpenUI 사용

[오픈UI](https://openui.com)생성 UI에 대한 개방형 표준입니다. 컴팩트 스트리밍 우선 언어(OpenUI Lang)를 React 런타임 및 내장 구성 요소 라이브러리와 결합하여 Model 출력이 스트리밍할 때 구조화된 UI로 렌더링될 수 있습니다.

OpenUI는 다음을 통해 Mastra에 연결됩니다.[AG-UI protocol](https://docs.ag-ui.com). The `@ag-ui/mastra`어댑터는 마스트라를 감쌉니다`Agent`그리고 OpenUI의 AG-UI 이벤트를 내보냅니다.`agUIAdapter()`클라이언트에서 구문 분석합니다.

> **팁:** 전체 작업 예제를 보려면 다음을 참조하세요.[`mastra-chat`](https://github.com/thesysdev/openui/tree/main/examples/mastra-chat) example in the OpenUI repository.

## 통합 가이드

Next.js API 경로에 Mastra를 포함하고 OpenUI를 연결하세요.`<AgentInterface />` 채팅 화면을 AG-UI 프로토콜을 통해 연결합니다.

1. 새로운 OpenUI 앱을 스캐폴드합니다.

   **npm**:

   ```bash
   npx @openuidev/cli@latest create --name openui-mastra-chat
   ```

   **pnpm**:

   ```bash
   pnpm dlx @openuidev/cli@latest create --name openui-mastra-chat
   ```

   **Yarn**:

   ```bash
   yarn dlx @openuidev/cli@latest create --name openui-mastra-chat
   ```

   **Bun**:

   ```bash
   bun x @openuidev/cli@latest create --name openui-mastra-chat
   ```

   새로 생성된 프로젝트 디렉터리로 이동합니다.

   ```bash
   cd openui-mastra-chat
   ```

   스캐폴드된 앱은 다음 구조를 가진 Next.js 프로젝트입니다.

   ```bash
   openui-mastra-chat
   └── src
       ├── app
       │   ├── api
       │   │   └── chat
       │   │       └── route.ts
       │   ├── globals.css
       │   ├── layout.tsx
       │   └── page.tsx
       ├── generated
       │   └── system-prompt.txt
       └── library.ts
   ```

   채팅 경로는 다음 위치에 있습니다.`src/app/api/chat/route.ts`, the chat surface in `src/app/page.tsx`, and the component library in `src/library.ts`. The OpenUI CLI writes `src/generated/system-prompt.txt` 를 라이브러리에서 생성하며, 라이브러리가 변경될 때마다 다시 생성합니다.

   OpenAI 키를 다음에 추가하세요.`.env.local`:

   ```bash
   OPENAI_API_KEY=sk-...
   ```

   > **노트:** OpenUI에는 Model 공급자 키가 필요합니다. Mastra가 지원하는 공급자를 사용하고 다음 단계에서 Agent 구성을 조정하세요.

2. Mastra 패키지와 Mastra용 AG-UI 어댑터를 설치합니다.

   **npm**:

   ```bash
   npm install @mastra/core @ag-ui/mastra @ag-ui/core zod
   ```

   **pnpm**:

   ```bash
   pnpm add @mastra/core @ag-ui/mastra @ag-ui/core zod
   ```

   **Yarn**:

   ```bash
   yarn add @mastra/core @ag-ui/mastra @ag-ui/core zod
   ```

   **Bun**:

   ```bash
   bun add @mastra/core @ag-ui/mastra @ag-ui/core zod
   ```

   `@ag-ui/mastra`마스트라를 감싸다`Agent` in a `MastraAgent` that emits [AG-UI protocol](https://docs.ag-ui.com) events. OpenUI's `agUIAdapter()` consumes those events on the client.

3. 열려 있는`src/app/api/chat/route.ts`. Define any tools your agent needs with `createTool` from `@mastra/core/tools`:

   ```typescript
   import { createTool } from '@mastra/core/tools'
   import { z } from 'zod'

   const getWeather = createTool({
     id: 'get_weather',
     description: 'Get current weather for a city.',
     inputSchema: z.object({ location: z.string().describe('City name') }),
     execute: async ({ location }) => {
       return { location, temperature_celsius: 22, condition: 'Clear' }
     },
   })
   ```

   마스트라를 감싸다`Agent` in `MastraAgent`. Agent가 OpenUI 컴포넌트 라이브러리를 사용하는 방법을 알 수 있도록 생성된 system Prompt를 주입합니다:

   ```typescript
   import { MastraAgent } from '@ag-ui/mastra'
   import { Agent } from '@mastra/core/agent'
   import { readFileSync } from 'fs'
   import { join } from 'path'

   const systemPrompt = readFileSync(join(process.cwd(), 'src/generated/system-prompt.txt'), 'utf-8')

   const agent = new MastraAgent({
     agent: new Agent({
       id: 'openui-agent',
       name: 'OpenUI Agent',
       instructions: `You are a helpful assistant. Use tools when relevant.\n\n${systemPrompt}`,
       model: {
         id: 'openai/gpt-5.6-sol',
         apiKey: process.env.OPENAI_API_KEY,
       },
       tools: { getWeather },
     }),
     resourceId: 'chat-user',
   })
   ```

   내보내기`POST` handler는 Agent의 AG-UI 이벤트를 Server-Sent Events(SSE)로 스트리밍합니다:

   ```typescript
   import type { Message } from '@ag-ui/core'
   import { NextRequest } from 'next/server'

   export async function POST(req: NextRequest) {
     const { messages, threadId }: { messages: Message[]; threadId: string } = await req.json()
     const encoder = new TextEncoder()

     const stream = new ReadableStream({
       start(controller) {
         const subscription = agent
           .run({ messages, threadId, runId: crypto.randomUUID(), tools: [], context: [] })
           .subscribe({
             next: event => {
               controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`))
             },
             complete: () => {
               controller.enqueue(encoder.encode('data: [DONE]\n\n'))
               controller.close()
             },
             error: error => {
               controller.enqueue(
                 encoder.encode(`data: ${JSON.stringify({ error: error.message })}\n\n`),
               )
               controller.close()
             },
           })

         req.signal.addEventListener('abort', () => subscription.unsubscribe())
       },
     })

     return new Response(stream, {
       headers: {
         'Content-Type': 'text/event-stream',
         'Cache-Control': 'no-cache, no-transform',
         Connection: 'keep-alive',
       },
     })
   }
   ```

4. OpenUI 연결`<AgentInterface />` chat surface to the route. Build an `llm` adapter with `fetchLLM()` and set `streamAdapter` to `agUIAdapter()` so OpenUI knows to parse AG-UI events.

   ```tsx
   'use client'

   import '@openuidev/react-ui/components.css'

   import { AgentInterface, agUIAdapter, fetchLLM } from '@openuidev/react-ui'
   import { openuiChatLibrary } from '@openuidev/react-ui/genui-lib'

   const llm = fetchLLM({
     url: '/api/chat',
     streamAdapter: agUIAdapter(),
   })

   export default function Page() {
     return (
       <div className="relative h-screen w-screen overflow-hidden">
         <AgentInterface llm={llm} componentLibrary={openuiChatLibrary} />
       </div>
     )
   }
   ```

   그만큼`componentLibrary` prop은 Model이 생성할 수 있는 컴포넌트를 제어합니다. `openuiChatLibrary` 를 자체 라이브러리로 교체하여 출력을 제한하거나 확장합니다.

5. 개발 서버를 시작합니다.

   **npm**:

   ```bash
   npm run dev
   ```

   **pnpm**:

   ```bash
   pnpm run dev
   ```

   **Yarn**:

   ```bash
   yarn dev
   ```

   **Bun**:

   ```bash
   bun run dev
   ```

   열려 있는<http://localhost:3000>. 이제 OpenUI 채팅 화면을 통해 Mastra Agent와 채팅할 수 있으며, Model이 스트리밍하는 동안 구조화된 UI가 점진적으로 렌더링됩니다.

## AG-UI를 사용한 스트리밍

OpenUI는[AG-UI protocol](https://docs.ag-ui.com). 이는 AI Agent를 위한 전송 방식 독립적인 형식 지정 이벤트 스트림입니다. `@ag-ui/mastra` translates a Mastra `Agent` into this protocol:

- 서버가 호출`agent.run({ messages, threadId, runId, ... })` 를 사용하며, 내보낸 각 이벤트를 SSE 메시지로 직렬화합니다.
- 클라이언트가 통과`fetchLLM({ streamAdapter: agUIAdapter() })` to `<AgentInterface />`. 이는 SSE 스트림을 OpenUI Lang 렌더링을 구동하는 내부 이벤트로 파싱합니다.

`threadId`여러 요청에 걸쳐 대화를 하나로 묶습니다.`runId` identifies a single execution. Generate a fresh `runId` per request and persist `threadId` on the client.

## 구성 요소 라이브러리

OpenUI는 구성 요소 라이브러리에서 UI를 생성합니다. 라이브러리는 사용 가능한 구성 요소, 해당 소품, Model이 해당 구성 요소를 사용하도록 지시하는 방법을 정의합니다.

### 내장 라이브러리

`@openuidev/react-ui`있는 그대로 사용할 수 있는 두 개의 라이브러리를 제공합니다.

- `openuiChatLibrary`: 채팅 인터페이스용 구성 요소(카드, 양식, 표, 차트)입니다.
- `openuiDashboardLibrary`: 대시보드 및 데이터가 많은 표면을 위한 구성 요소입니다.

도서관을 넘겨주세요`<AgentInterface componentLibrary={...} />` 를 사용해 해당 컴포넌트를 Model에서 사용할 수 있도록 합니다.

### 라이브러리 사용자 정의

출력을 제한하거나 확장하려면 다음에서 자신의 라이브러리를 정의하십시오.`src/library.ts` 를 만들고 컴포넌트의 일부를 내보냅니다. 해당 라이브러리를 `<AgentInterface />` 에 전달하고 라이브러리가 변경될 때마다 system Prompt를 다시 생성합니다:

**npm**:

```bash
npx @openuidev/cli generate src/library.ts --out src/generated/system-prompt.txt
```

**pnpm**:

```bash
pnpm dlx @openuidev/cli generate src/library.ts --out src/generated/system-prompt.txt
```

**Yarn**:

```bash
yarn dlx @openuidev/cli generate src/library.ts --out src/generated/system-prompt.txt
```

**Bun**:

```bash
bun x @openuidev/cli generate src/library.ts --out src/generated/system-prompt.txt
```

생성된 Prompt는 API 경로로 읽혀지고 Agent의 Prompt에 병합됩니다.`instructions`, 따라서 Agent는 어떤 컴포넌트를 출력할 수 있는지 정확히 알 수 있습니다.