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

# Intégrer Mastra à votre projet Astro

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

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.

> **Remarque:** Ce guide montre comment utiliser Astro avec React et un rendu complet côté serveur (SSR), mais Astro peut être associé à Mastra de nombreuses manières. Vous pouvez [activer le SSR](https://docs.astro.build/en/guides/on-demand-rendering/#enabling-on-demand-rendering) fichier par fichier et utiliser d’autres frameworks comme Svelte, Vue, Solid ou Preact. Vous pouvez également créer une interface de chat avec Astro et appeler des endpoints [nativement dans Astro](https://docs.astro.build/en/recipes/call-endpoints/).

## Avant de commencer

- Vous aurez besoin d’une clé d’API fournie par un [Provider de modèle](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 nouvelle application Astro (facultatif)

Si vous disposez déjà d’une application Astro, passez à l’étape suivante. Votre application Astro doit être configurée comme suit :

- Utiliser le SSR (`output: "server"` dans `astro.config.mjs`)
- Utiliser l’[intégration React](https://docs.astro.build/en/guides/integrations-guide/react/)
- Installer Tailwind

Pour prendre en charge le [rendu à la demande](https://docs.astro.build/en/guides/on-demand-rendering/), ce guide utilise l’[adaptateur Node.js](https://docs.astro.build/en/guides/integrations-guide/node/), mais n’importe quel adaptateur de serveur pris en charge convient.

**npm**:

```bash
npm create astro@latest mastra-astro -- --add node --add react --add tailwind --install --skip-houston --template minimal --git
```

**pnpm**:

```bash
pnpm create astro mastra-astro --add node --add react --add tailwind --install --skip-houston --template minimal --git
```

**Yarn**:

```bash
yarn create astro mastra-astro --add node --add react --add tailwind --install --skip-houston --template minimal --git
```

**Bun**:

```bash
bunx create-astro mastra-astro --add node --add react --add tailwind --install --skip-houston --template minimal --git
```

Cette commande crée un projet nommé `mastra-astro`, mais vous pouvez choisir un autre nom.

Accédez à votre projet avec `cd`, puis modifiez le fichier `astro.config.mjs` pour définir le [paramètre `output`](https://docs.astro.build/en/reference/configuration-reference/#output) sur `"server"` :

```js
// @ts-check
import { defineConfig } from 'astro/config'

import node from '@astrojs/node'
import react from '@astrojs/react'
import tailwindcss from '@tailwindcss/vite'

// https://astro.build/config
export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'standalone',
  }),

  integrations: [react()],

  vite: {
    plugins: [tailwindcss()],
  },
})
```

Modifiez le fichier `tsconfig.json` pour 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, puis 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, 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 Astro au cours des étapes suivantes.

## Installer AI SDK UI et AI Elements

Installez AI SDK UI avec 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é, sélectionnez 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 toute la bibliothèque de composants UI d’AI Elements dans un dossier `@/components/ai-elements`.

## Créer une route de chat

Créez `src/pages/api/chat.ts` :

```ts
import type { APIRoute } from 'astro'
import { handleChatStream } from '@mastra/ai-sdk'
import { toAISdkV5Messages } from '@mastra/ai-sdk/ui'
import { createUIMessageStreamResponse } from 'ai'
import { mastra } from '@/mastra'

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

export const POST: APIRoute = async ({ request }) => {
  const params = await request.json()
  const stream = await handleChatStream({
    mastra,
    agentId: 'weather-agent',
    params: {
      ...params,
      memory: {
        ...params.memory,
        thread: THREAD_ID,
        resource: RESOURCE_ID,
      },
    },
  })

  return createUIMessageStreamResponse({ stream })
}

export const GET: APIRoute = async () => {
  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 Response.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 un composant de chat

Créez `src/components/chat.tsx` :

```tsx
import '@/styles/global.css'
import { useEffect, useState } 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'

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()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) à 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>`](https://ai-sdk.dev/elements/components/message#messageresponse-) et les appels de Tools avec le composant [`<Tool>`](https://ai-sdk.dev/elements/components/tool).

## Afficher le composant de chat

La dernière étape consiste à afficher le composant de chat sur votre page d’index. Modifiez `src/pages/index.astro` :

```html
---
import Chat from '@/components/chat';
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width" />
    <meta name="generator" content="{Astro.generator}" />
    <title>Astro</title>
  </head>
  <body>
    <Chat client:load />
  </body>
</html>
```

Importez le composant `Chat` et ajoutez-le au corps de la page avec la [directive](https://docs.astro.build/en/reference/directives-reference/#client-directives) `client:load` afin qu’il s’exécute côté client.

## Tester votre Agent

1. Lancez votre application Astro avec `npm run dev`
2. Ouvrez le chat à l’adresse <http://localhost:4321>
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

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

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)
- Ajouter des [Tools](https://mastra.zisheng.pro/fr/docs/agents/using-tools) à votre Agent
- Ajouter une [Memory](https://mastra.zisheng.pro/fr/docs/memory/overview) similaire à la mémoire humaine à votre Agent

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

- Intégrer Mastra à [AI SDK UI](https://mastra.zisheng.pro/fr/guides/build-your-ui/ai-sdk-ui)
- Déployer votre Agent [où vous le souhaitez](https://mastra.zisheng.pro/fr/docs/deployment/overview)