> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt # OpenUI を使用する [OpenUI](https://openui.com) は Generative UI のオープン標準です。ストリーミングを重視したコンパクトな言語（OpenUI Lang）と、React Runtime および組み込みコンポーネントライブラリを組み合わせ、ストリーミング中のモデル出力を構造化 UI としてレンダリングできます。 OpenUI は [AG-UI プロトコル](https://docs.ag-ui.com)を通じて Mastra に接続します。`@ag-ui/mastra` Adapter が Mastra `Agent` をラップして AG-UI イベントを送出し、クライアント上の OpenUI `agUIAdapter()` がそれを解析します。 > **ヒント:** 完全に動作する例については、OpenUI リポジトリの [`mastra-chat`](https://github.com/thesysdev/openui/tree/main/examples/mastra-chat) を参照してください。 ## 統合ガイド Mastra を Next.js API Route に組み込み、AG-UI プロトコルを介して OpenUI の `` チャット画面に接続します。 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`、チャット画面は `src/app/page.tsx`、コンポーネントライブラリは `src/library.ts` にあります。OpenUI CLI はライブラリから `src/generated/system-prompt.txt` を生成します。ライブラリを変更した場合は、必ず再生成してください。 OpenAI キーを `.env.local` に追加します。 ```bash OPENAI_API_KEY=sk-... ``` > **注記:** OpenUI にはモデル Provider のキーが必要です。Mastra がサポートする任意の Provider を使用し、次の Step で Agent 設定を変更してください。 2. Mastra パッケージと Mastra 用 AG-UI Adapter をインストールします。 **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` は Mastra `Agent` を、[AG-UI プロトコル](https://docs.ag-ui.com)イベントを送出する `MastraAgent` でラップします。クライアント上の OpenUI `agUIAdapter()` がこれらのイベントを使用します。 3. `src/app/api/chat/route.ts` を開きます。`@mastra/core/tools` の `createTool` を使用して、Agent に必要な Tool を定義します。 ```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' } }, }) ``` Mastra `Agent` を `MastraAgent` でラップします。Agent が OpenUI コンポーネントライブラリの使用方法を理解できるように、生成されたシステムプロンプトを注入します。 ```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', }) ``` Agent の AG-UI イベントを Server-Sent Events（SSE）としてストリーミングする `POST` Handler をエクスポートします。 ```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 の `` チャット画面をルートに接続します。`fetchLLM()` で `llm` Adapter を作成し、`streamAdapter` を `agUIAdapter()` に設定して、OpenUI が AG-UI イベントを解析できるようにします。 ```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 (
) } ``` `componentLibrary` Prop は、モデルが生成できるコンポーネントを制御します。出力を制限または拡張するには、`openuiChatLibrary` を独自のライブラリに置き換えます。 5. 開発サーバーを起動します。 **npm**: ```bash npm run dev ``` **pnpm**: ```bash pnpm run dev ``` **Yarn**: ```bash yarn dev ``` **Bun**: ```bash bun run dev ``` を開きます。OpenUI チャット画面から Mastra Agent とチャットできるようになり、モデルのストリーミングに合わせて構造化 UI が段階的にレンダリングされます。 ## AG-UI でストリーミングする OpenUI は、AI Agent 用の型付きイベントを転送する、Transport に依存しない [AG-UI プロトコル](https://docs.ag-ui.com)を使用します。`@ag-ui/mastra` は Mastra `Agent` をこのプロトコルに変換します。 - サーバーは `agent.run({ messages, threadId, runId, ... })` を呼び出し、送出された各イベントを SSE メッセージとしてシリアライズします。 - クライアントは `` に `fetchLLM({ streamAdapter: agUIAdapter() })` を渡します。これにより、SSE ストリームが OpenUI Lang のレンダリングを駆動する内部イベントに解析されます。 `threadId` はリクエスト間で会話を関連付け、`runId` は 1 回の実行を識別します。リクエストごとに新しい `runId` を生成し、クライアント側で `threadId` を永続化してください。 ## コンポーネントライブラリ OpenUI はコンポーネントライブラリから UI を生成します。ライブラリは、利用可能なコンポーネント、その Props、モデルに使用方法を指示する方法を定義します。 ### 組み込みライブラリ `@openuidev/react-ui` には、そのまま使用できる 2 つのライブラリがあります。 - `openuiChatLibrary`：チャットインターフェース用のコンポーネント（カード、フォーム、テーブル、チャート）。 - `openuiDashboardLibrary`：ダッシュボードやデータ量の多い画面向けのコンポーネント。 ライブラリを `` に渡すと、そのコンポーネントをモデルで使用できるようになります。 ### ライブラリをカスタマイズする 出力を制限または拡張するには、`src/library.ts` に独自のライブラリを定義し、コンポーネントの一部をエクスポートします。そのライブラリを `` に渡し、ライブラリを変更するたびにシステムプロンプトを再生成します。 **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 ``` 生成されたプロンプトは API Route で読み込まれ、Agent の `instructions` にマージされるため、Agent は送出できるコンポーネントを正確に認識できます。