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

# Utiliser OpenUI

[OpenUI](https://openui.com) est une norme ouverte pour les interfaces utilisateur génératives. Elle associe un langage compact conçu pour le streaming, OpenUI Lang, à un runtime React et à des bibliothèques de composants intégrées, afin que la sortie du modèle soit rendue sous la forme d’une interface structurée pendant le streaming.

OpenUI se connecte à Mastra via le [protocole AG-UI](https://docs.ag-ui.com). L’adaptateur `@ag-ui/mastra` encapsule un `Agent` Mastra et émet des événements AG-UI, que `agUIAdapter()` d’OpenUI analyse côté client.

> **Astuce:** Pour un exemple complet et fonctionnel, consultez l’exemple [`mastra-chat`](https://github.com/thesysdev/openui/tree/main/examples/mastra-chat) dans le dépôt OpenUI.

## Guide d’intégration

Intégrez Mastra dans votre route d’API Next.js et connectez-lui une surface de chat OpenUI `<AgentInterface />` via le protocole AG-UI.

1. Générez une nouvelle application 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
   ```

   Accédez au répertoire de votre nouveau projet :

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

   L’application générée est un projet Next.js ayant la structure suivante :

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

   La route de chat se trouve dans `src/app/api/chat/route.ts`, la surface de chat dans `src/app/page.tsx` et la bibliothèque de composants dans `src/library.ts`. La CLI OpenUI écrit `src/generated/system-prompt.txt` à partir de votre bibliothèque ; régénérez-le à chaque modification de la bibliothèque.

   Ajoutez votre clé OpenAI à `.env.local` :

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

   > **Remarque:** OpenUI requiert une clé de fournisseur de modèles. Utilisez n’importe quel fournisseur pris en charge par Mastra et ajustez la configuration de l’Agent à l’étape suivante.

2. Installez les packages Mastra et l’adaptateur AG-UI pour Mastra :

   **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` encapsule un `Agent` Mastra dans un `MastraAgent` qui émet des événements du [protocole AG-UI](https://docs.ag-ui.com). `agUIAdapter()` d’OpenUI consomme ces événements côté client.

3. Ouvrez `src/app/api/chat/route.ts`. Définissez tous les Tools dont votre Agent a besoin avec `createTool` depuis `@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' }
     },
   })
   ```

   Encapsulez un `Agent` Mastra dans `MastraAgent`. Injectez le prompt système généré afin que l’Agent sache utiliser la bibliothèque de composants 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',
   })
   ```

   Exportez un gestionnaire `POST` qui diffuse les événements AG-UI de l’Agent sous forme d’événements envoyés par le serveur, ou 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. Connectez la surface de chat OpenUI `<AgentInterface />` à la route. Créez un adaptateur `llm` avec `fetchLLM()` et définissez `streamAdapter` sur `agUIAdapter()` afin qu’OpenUI sache analyser les événements 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 (
       <div className="relative h-screen w-screen overflow-hidden">
         <AgentInterface llm={llm} componentLibrary={openuiChatLibrary} />
       </div>
     )
   }
   ```

   La prop `componentLibrary` contrôle les composants que le modèle peut générer. Remplacez `openuiChatLibrary` par votre propre bibliothèque pour restreindre ou étendre la sortie.

5. Démarrez le serveur de développement :

   **npm**:

   ```bash
   npm run dev
   ```

   **pnpm**:

   ```bash
   pnpm run dev
   ```

   **Yarn**:

   ```bash
   yarn dev
   ```

   **Bun**:

   ```bash
   bun run dev
   ```

   Ouvrez <http://localhost:3000>. Vous pouvez maintenant converser avec votre Agent Mastra via la surface de chat OpenUI, l’interface structurée étant rendue progressivement pendant le streaming du modèle.

## Streaming avec AG-UI

OpenUI consomme le [protocole AG-UI](https://docs.ag-ui.com), un flux d’événements typés destiné aux Agents IA et indépendant du transport. `@ag-ui/mastra` traduit un `Agent` Mastra dans ce protocole :

- Le serveur appelle `agent.run({ messages, threadId, runId, ... })` et sérialise chaque événement émis sous la forme d’un message SSE.
- Le client transmet `fetchLLM({ streamAdapter: agUIAdapter() })` à `<AgentInterface />`, qui analyse le flux SSE pour produire les événements internes pilotant le rendu d’OpenUI Lang.

`threadId` relie une conversation entre les requêtes et `runId` identifie une exécution unique. Générez un nouveau `runId` pour chaque requête et conservez `threadId` côté client.

## Bibliothèques de composants

OpenUI génère une interface à partir d’une bibliothèque de composants. Cette bibliothèque définit les composants disponibles, leurs props et la manière dont le modèle doit les utiliser.

### Bibliothèques intégrées

`@openuidev/react-ui` fournit deux bibliothèques prêtes à l’emploi :

- `openuiChatLibrary` : composants pour les interfaces de chat, notamment cartes, formulaires, tableaux et graphiques.
- `openuiDashboardLibrary` : composants pour les tableaux de bord et les surfaces riches en données.

Transmettez la bibliothèque à `<AgentInterface componentLibrary={...} />` pour mettre ses composants à la disposition du modèle.

### Personnaliser la bibliothèque

Pour restreindre ou étendre la sortie, définissez votre propre bibliothèque dans `src/library.ts` et exportez un sous-ensemble de composants. Transmettez cette bibliothèque à `<AgentInterface />` et régénérez le prompt système à chaque modification de la bibliothèque :

**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
```

Le prompt généré est lu par la route d’API et fusionné dans les `instructions` de l’Agent, afin que celui-ci sache exactement quels composants il peut émettre.