Aller au contenu principal

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 et AI Elements pour créer une expérience de chat élégante et interactive.

Avant de commencer
Lien direct vers Avant de commencer

  • Vous aurez besoin d’une clé API provenant d’un Provider de modèles pris en charge. Si vous n’avez pas de préférence, utilisez OpenAI.
  • Installez Node.js v22.13.0 ou une version ultérieure

Créer une application React + Vite (facultatif)
Lien direct vers 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
Lien direct vers Initialiser le projet

Exécutez la commande suivante pour créer une application React + Vite :

npm create vite@latest 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 :

cd mastra-react

Tailwind
Lien direct vers Tailwind

Installez ensuite Tailwind :

npm install tailwindcss @tailwindcss/vite

Configurez les plugins Vite :

vite.config.ts
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 :

src/index.css
@import 'tailwindcss';

Ajoutez ces compilerOptions à tsconfig.json :

tsconfig.json
{
  // ...
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
    },
  },
}

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

tsconfig.app.json
{
  "compilerOptions": {
    // ...
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
    },
    // ...
  },
}

Initialiser Mastra
Lien direct vers Initialiser Mastra

Exécutez mastra init. Lorsque vous y êtes invité, choisissez un Provider (par exemple OpenAI) et saisissez votre clé :

npx 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
Lien direct vers Installer AI SDK UI et AI Elements

Installez AI SDK UI ainsi que l’adaptateur Mastra :

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

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

npx 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
Lien direct vers Créer une route de chat

Ouvrez ⁠src/mastra/index.ts et ajoutez une ⁠chatRoute() à 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().

src/mastra/index.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
Lien direct vers Ajouter l’interface de chat

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

src/App.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() 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> et présente les appels de Tool avec le composant <Tool>.

Tester votre Agent
Lien direct vers 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 :

    npx mastra dev

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

    npm 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
Lien direct vers É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
  • Donnez à votre Agent ses propres Tools
  • Ajoutez une mémoire 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 :

On this page