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

# Intégrer Mastra à votre projet React + Vite

Dans ce guide, vous allez créer avec Mastra un Agent d’IA capable d’appeler des Tools, puis le connecter à React en l’appelant directement depuis le serveur autonome de Mastra.

Vous utiliserez [AI SDK UI](https://ai-sdk.dev/docs/ai-sdk-ui/overview) et [AI Elements](https://ai-sdk.dev/elements) pour créer une expérience de chat élégante et interactive.

## Avant de commencer

- Vous aurez besoin d’une clé API provenant d’un [Provider de modèles](https://mastra.zisheng.pro/fr/models) pris en charge. Si vous n’avez pas de préférence, utilisez [OpenAI](https://mastra.zisheng.pro/fr/models/providers/openai).
- Installez Node.js `v22.13.0` ou une version ultérieure

## Créer une application React + Vite (facultatif)

Si vous disposez déjà d’une application React + Vite utilisant Tailwind, passez à l’étape suivante.

### Initialiser le projet

Exécutez la commande suivante pour [créer une application React + Vite](https://vite.dev/guide/#scaffolding-your-first-vite-project) :

**npm**:

```bash
npm create vite@latest mastra-react -- --template react-ts
```

**pnpm**:

```bash
pnpm create vite mastra-react --template react-ts
```

**Yarn**:

```bash
yarn create vite mastra-react --template react-ts
```

**Bun**:

```bash
bunx create-vite mastra-react --template react-ts
```

Cette commande crée un projet nommé `mastra-react`, mais vous pouvez choisir le nom de votre choix.

Accédez au répertoire de votre projet :

```bash
cd mastra-react
```

### Tailwind

Installez ensuite Tailwind :

**npm**:

```bash
npm install tailwindcss @tailwindcss/vite
```

**pnpm**:

```bash
pnpm add tailwindcss @tailwindcss/vite
```

**Yarn**:

```bash
yarn add tailwindcss @tailwindcss/vite
```

**Bun**:

```bash
bun add tailwindcss @tailwindcss/vite
```

Configurez les plugins Vite :

```typescript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})
```

Remplacez l’intégralité du contenu de `src/index.css` par ce qui suit :

```css
@import 'tailwindcss';
```

Ajoutez ces `compilerOptions` à `tsconfig.json` :

```jsonc
{
  // ...
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
    },
  },
}
```

Modifiez `tsconfig.app.json` afin de résoudre les chemins :

```jsonc
{
  "compilerOptions": {
    // ...
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
    },
    // ...
  },
}
```

## Initialiser Mastra

Exécutez [`mastra init`](https://mastra.zisheng.pro/fr/reference/cli/mastra). Lorsque vous y êtes invité, choisissez un Provider (par exemple OpenAI) et saisissez votre clé :

**npm**:

```bash
npx mastra@latest init
```

**pnpm**:

```bash
pnpm dlx mastra@latest init
```

**Yarn**:

```bash
yarn dlx mastra@latest init
```

**Bun**:

```bash
bun x mastra@latest init
```

Cette commande crée un dossier `src/mastra` contenant un exemple d’Agent météo et les fichiers suivants :

- `index.ts` — configuration de Mastra, y compris la mémoire
- `tools/weather-tool.ts` — Tool qui récupère la météo d’un lieu donné
- `agents/weather-agent.ts` — Agent météo doté d’une instruction qui utilise le Tool

Dans les étapes suivantes, vous appellerez `weather-agent.ts` depuis votre interface de chat.

## Installer AI SDK UI et AI Elements

Installez AI SDK UI ainsi que l’adaptateur Mastra :

**npm**:

```bash
npm install @mastra/ai-sdk@latest @ai-sdk/react ai
```

**pnpm**:

```bash
pnpm add @mastra/ai-sdk@latest @ai-sdk/react ai
```

**Yarn**:

```bash
yarn add @mastra/ai-sdk@latest @ai-sdk/react ai
```

**Bun**:

```bash
bun add @mastra/ai-sdk@latest @ai-sdk/react ai
```

Initialisez ensuite AI Elements. Lorsque vous y êtes invité, choisissez les options par défaut :

**npm**:

```bash
npx ai-elements@latest
```

**pnpm**:

```bash
pnpm dlx ai-elements@latest
```

**Yarn**:

```bash
yarn dlx ai-elements@latest
```

**Bun**:

```bash
bun x ai-elements@latest
```

Cette commande télécharge l’ensemble de la bibliothèque de composants d’interface AI Elements dans un dossier `@/components/ai-elements`.

## Créer une route de chat

Ouvrez ⁠`src/mastra/index.ts` et ajoutez une [⁠chatRoute()](https://mastra.zisheng.pro/fr/reference/ai-sdk/chat-route) à votre configuration. Elle crée une route d’API que votre frontend React peut appeler pour recevoir des réponses de chat compatibles avec AI SDK ; vous l’utiliserez ensuite avec ⁠useChat().

```ts
import { Mastra } from '@mastra/core/mastra'
// Existing imports...
import { chatRoute } from '@mastra/ai-sdk'

export const mastra = new Mastra({
  // Existing config...
  server: {
    apiRoutes: [
      chatRoute({
        path: '/chat/:agentId',
      }),
    ],
  },
})
```

## Ajouter l’interface de chat

Remplacez le fichier `src/App.tsx` afin de créer une interface de chat :

```tsx
import * as React from 'react'
import { DefaultChatTransport, type ToolUIPart } from 'ai'
import { useChat } from '@ai-sdk/react'

import {
  PromptInput,
  PromptInputBody,
  PromptInputTextarea,
} from '@/components/ai-elements/prompt-input'

import {
  Conversation,
  ConversationContent,
  ConversationScrollButton,
} from '@/components/ai-elements/conversation'

import { Message, MessageContent, MessageResponse } from '@/components/ai-elements/message'

import { Tool, ToolHeader, ToolContent, ToolInput, ToolOutput } from '@/components/ai-elements/tool'

export default function App() {
  const [input, setInput] = React.useState<string>('')

  const { messages, sendMessage, status } = useChat({
    transport: new DefaultChatTransport({
      api: 'http://localhost:4111/chat/weather-agent',
    }),
  })

  const handleSubmit = async () => {
    if (!input.trim()) return

    sendMessage({ text: input })
    setInput('')
  }

  return (
    <div className="relative mx-auto size-full h-screen max-w-4xl p-6">
      <div className="flex h-full flex-col">
        <Conversation className="h-full">
          <ConversationContent>
            {messages.map(message => (
              <div key={message.id}>
                {message.parts?.map((part, i) => {
                  if (part.type === 'text') {
                    return (
                      <Message key={`${message.id}-${i}`} from={message.role}>
                        <MessageContent>
                          <MessageResponse>{part.text}</MessageResponse>
                        </MessageContent>
                      </Message>
                    )
                  }

                  if (part.type?.startsWith('tool-')) {
                    return (
                      <Tool key={`${message.id}-${i}`}>
                        <ToolHeader
                          type={(part as ToolUIPart).type}
                          state={(part as ToolUIPart).state || 'output-available'}
                          className="cursor-pointer"
                        />
                        <ToolContent>
                          <ToolInput input={(part as ToolUIPart).input || {}} />
                          <ToolOutput
                            output={(part as ToolUIPart).output}
                            errorText={(part as ToolUIPart).errorText}
                          />
                        </ToolContent>
                      </Tool>
                    )
                  }

                  return null
                })}
              </div>
            ))}
            <ConversationScrollButton />
          </ConversationContent>
        </Conversation>
        <PromptInput onSubmit={handleSubmit} className="mt-20">
          <PromptInputBody>
            <PromptInputTextarea
              onChange={e => setInput(e.target.value)}
              className="md:leading-10"
              value={input}
              placeholder="Ask about the weather..."
              disabled={status !== 'ready'}
            />
          </PromptInputBody>
        </PromptInput>
      </div>
    </div>
  )
}
```

Ce composant connecte [`useChat()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) au point de terminaison `chat/weather-agent`, lui envoie les instructions et reçoit la réponse en streaming par fragments.

Il affiche le texte de la réponse avec le composant [`<MessageResponse>`](https://ai-sdk.dev/elements/components/message#messageresponse-) et présente les appels de Tool avec le composant [`<Tool>`](https://ai-sdk.dev/elements/components/tool).

## Tester votre Agent

Pour tester votre Agent avec l’interface de chat, exécutez simultanément le serveur Mastra et le serveur de développement Vite.

1. Démarrez le serveur de développement Mastra :

   **npm**:

   ```bash
   npx mastra dev
   ```

   **pnpm**:

   ```bash
   pnpm dlx mastra dev
   ```

   **Yarn**:

   ```bash
   yarn dlx mastra dev
   ```

   **Bun**:

   ```bash
   bun x mastra dev
   ```

2. Dans un autre terminal, démarrez le serveur de développement Vite :

   **npm**:

   ```bash
   npm run dev
   ```

   **pnpm**:

   ```bash
   pnpm run dev
   ```

   **Yarn**:

   ```bash
   yarn dev
   ```

   **Bun**:

   ```bash
   bun run dev
   ```

3. Ouvrez votre application à l’adresse <http://localhost:5173>

4. Posez une question sur la météo. Si votre clé API est correctement configurée, vous obtiendrez une réponse

## Étapes suivantes

Félicitations, vous avez créé votre Agent Mastra avec React ! 🎉

Vous pouvez maintenant enrichir le projet avec vos propres Tools et votre propre logique :

- En savoir plus sur les [Agents](https://mastra.zisheng.pro/fr/docs/agents/overview)
- Donnez à votre Agent ses propres [Tools](https://mastra.zisheng.pro/fr/docs/agents/using-tools)
- Ajoutez une [mémoire](https://mastra.zisheng.pro/fr/docs/memory/overview) semblable à celle des humains à votre Agent

Lorsque vous êtes prêt, découvrez plus en détail l’intégration de Mastra avec AI SDK UI et React, ainsi que le déploiement de votre Agent sur n’importe quelle plateforme :

- Intégrez Mastra à [AI SDK UI](https://mastra.zisheng.pro/fr/guides/build-your-ui/ai-sdk-ui)
- Déployez votre Agent [sur la plateforme de votre choix](https://mastra.zisheng.pro/fr/docs/deployment/overview)