Aller au contenu principal

Intégrer Mastra à votre projet Next.js

Dans ce guide, vous allez créer avec Mastra un Agent d’IA capable d’appeler des Tools, puis le connecter à Next.js en l’important et en l’appelant directement depuis vos routes.

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é d’API fournie par un Provider de modèle 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 nouvelle application Next.js (facultatif)
Lien direct vers Créer une nouvelle application Next.js (facultatif)

Si vous disposez déjà d’une application Next.js, passez à l’étape suivante.

Exécutez la commande suivante pour créer une nouvelle application Next.js :

npx create-next-app@latest my-nextjs-agent --yes --ts --eslint --tailwind --src-dir --app --turbopack --no-react-compiler --no-import-alias

Cette commande crée un projet nommé my-nextjs-agent, mais vous pouvez choisir un autre nom.

Initialiser Mastra
Lien direct vers Initialiser Mastra

Accédez à votre projet Next.js :

cd my-nextjs-agent

Exécutez mastra init. Lorsque vous y êtes invité, choisissez un Provider, par exemple OpenAI, puis 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, notamment la Memory
  • tools/weather-tool.ts : Tool permettant de récupérer la météo d’un lieu donné
  • agents/weather-agent.ts : Agent météo dont le prompt utilise le Tool

Vous appellerez weather-agent.ts depuis vos routes Next.js au cours des étapes suivantes.

Utiliser Studio avec Next.js

Si vous souhaitez exécuter Studio avec votre application Next.js et leur faire partager la même base de données, modifiez l’URL de stockage dans src/mastra/index.ts afin d’utiliser un chemin absolu :

url: 'file:/absolute/path/to/your/project/mastra.db'

Les chemins relatifs sont résolus à partir du répertoire de travail de chaque processus, qui diffère entre next dev et mastra dev.

Installer AI SDK UI et AI Elements
Lien direct vers Installer AI SDK UI et AI Elements

Installez AI SDK UI avec l’adaptateur Mastra :

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

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

npx ai-elements@latest

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

Créer une route de chat
Lien direct vers Créer une route de chat

Créez src/app/api/chat/route.ts :

src/app/api/chat/route.ts
import { handleChatStream } from '@mastra/ai-sdk'
import { toAISdkV5Messages } from '@mastra/ai-sdk/ui'
import { createUIMessageStreamResponse } from 'ai'
import { mastra } from '@/mastra'
import { NextResponse } from 'next/server'

const THREAD_ID = 'example-user-id'
const RESOURCE_ID = 'weather-chat'

export async function POST(req: Request) {
  const params = await req.json()
  const stream = await handleChatStream({
    mastra,
    agentId: 'weather-agent',
    params: {
      ...params,
      memory: {
        ...params.memory,
        thread: THREAD_ID,
        resource: RESOURCE_ID,
      },
    },
  })
  return createUIMessageStreamResponse({ stream })
}

export async function GET() {
  const memory = await mastra.getAgentById('weather-agent').getMemory()
  let response = null

  try {
    response = await memory?.recall({
      threadId: THREAD_ID,
      resourceId: RESOURCE_ID,
    })
  } catch {
    console.log('No previous messages found.')
  }

  const uiMessages = toAISdkV5Messages(response?.messages || [])

  return NextResponse.json(uiMessages)
}

La route POST accepte un prompt et renvoie la réponse diffusée de l’Agent au format AI SDK, tandis que la route GET récupère l’historique des messages depuis la Memory afin que l’UI puisse être hydratée lorsque le client recharge la page.

Créer une page de chat
Lien direct vers Créer une page de chat

Créez src/app/chat/page.tsx :

src/app/chat/page.tsx
'use client'

import '@/app/globals.css'
import { useEffect, useState } from 'react'
import { DefaultChatTransport, 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'

function Chat() {
  const [input, setInput] = useState<string>('')

  const { messages, setMessages, sendMessage, status } = useChat({
    transport: new DefaultChatTransport({
      api: '/api/chat',
    }),
  })

  useEffect(() => {
    const fetchMessages = async () => {
      const res = await fetch('/api/chat')
      const data = await res.json()
      setMessages([...data])
    }
    fetchMessages()
  }, [setMessages])

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

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

  return (
    <div className="relative size-full h-screen w-full 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="Type your message..."
              disabled={status !== 'ready'}
            />
          </PromptInputBody>
        </PromptInput>
      </div>
    </div>
  )
}

export default Chat

Ce composant connecte useChat() à l’endpoint api/chat, auquel il envoie les prompts et dont il reçoit la réponse sous forme de fragments diffusés.

Il affiche le texte de la réponse à l’aide du composant <MessageResponse> et les appels de Tools avec le composant <Tool>.

Tester votre Agent
Lien direct vers Tester votre Agent

  1. Lancez votre application Next.js avec npm run dev
  2. Ouvrez le chat à l’adresse http://localhost:3000/chat
  3. Posez une question sur la météo. Si votre clé d’API est correctement configurée, vous recevrez une réponse

Étapes suivantes
Lien direct vers Étapes suivantes

Félicitations, vous avez créé votre Agent Mastra avec Next.js ! 🎉

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

  • En savoir plus sur les Agents
  • Ajouter des Tools à votre Agent
  • Ajouter une Memory similaire à la mémoire humaine à votre Agent

Lorsque vous serez prêt, découvrez comment Mastra s’intègre à AI SDK UI et Next.js, et comment déployer votre Agent où vous le souhaitez, notamment sur Vercel :

On this page