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

# Utiliser CopilotKit

[CopilotKit](https://www.copilotkit.ai/) fournit des composants React permettant d’intégrer rapidement des copilotes IA personnalisables dans votre application. Associé à Mastra, il vous permet de créer des applications IA avec synchronisation d’état bidirectionnelle et interfaces utilisateur interactives.

CopilotKit communique avec Mastra via le [protocole AG-UI](https://docs.ag-ui.com/). Le package `@ag-ui/mastra` expose vos Agents Mastra sous forme d’endpoint AG-UI, que les hooks et composants React de CopilotKit consomment. Cela ouvre un éventail d’expériences allant au-delà du chat classique : [interface utilisateur générative, human-in-the-loop et Tools frontend](https://mastra.zisheng.pro/fr/guides/build-your-ui/copilotkit/generative-ui), ainsi que le déploiement du même Agent dans des [canaux de messagerie comme Slack](https://mastra.zisheng.pro/fr/guides/build-your-ui/copilotkit/channels).

Consultez la [documentation CopilotKit](https://docs.copilotkit.ai/) pour en apprendre davantage sur les concepts, composants et modèles d’utilisation avancés de CopilotKit.

> **Info:** Pour une approche d’intégration full stack dans laquelle Mastra s’exécute directement dans vos routes d’API Next.js, consultez le guide [CopilotKit Quickstart](https://docs.copilotkit.ai/mastra/quickstart).

Consultez le [« UI Dojo »](https://ui-dojo.mastra.ai/) de Mastra pour voir des exemples concrets d’intégration de CopilotKit avec Mastra.

## Guide d’intégration

Exécutez Mastra comme serveur autonome et connectez votre frontend Next.js, avec CopilotKit, à ses endpoints API.

1. Configurez la structure de vos répertoires. Elle peut, par exemple, ressembler à ceci :

   ```bash
   project-root
   ├── mastra-server
   │   ├── src
   │   │   └── mastra
   │   └── package.json
   └── my-copilot-app
       └── package.json
   ```

   Initialisez votre serveur Mastra :

   **npm**:

   ```bash
   npx create-mastra@latest
   ```

   **pnpm**:

   ```bash
   pnpm dlx create-mastra@latest
   ```

   **Yarn**:

   ```bash
   yarn dlx create-mastra@latest
   ```

   **Bun**:

   ```bash
   bun x create-mastra@latest
   ```

   Cette commande ouvre un assistant interactif qui génère le squelette d’un nouveau projet Mastra. Suivez les prompts pour créer votre projet de serveur.

   Accédez au répertoire de serveur Mastra qui vient d’être créé :

   ```bash
   cd mastra-server # Replace with the actual directory name you provided
   ```

   Vous disposez maintenant d’un projet de serveur Mastra de base prêt à l’emploi.

   > **Remarque:** Vérifiez que vous avez défini les variables d’environnement appropriées pour votre fournisseur de LLM dans le fichier `.env`.

2. Créez une route de chat pour le frontend CopilotKit à l’aide de l’assistant `registerCopilotKit()` de `@ag-ui/mastra`. Ajoutez-le à votre projet Mastra, ainsi que ses dépendances pairs :

   **npm**:

   ```bash
   npm install @ag-ui/mastra @mastra/client-js @mastra/core @ag-ui/core @ag-ui/client @copilotkit/runtime
   ```

   **pnpm**:

   ```bash
   pnpm add @ag-ui/mastra @mastra/client-js @mastra/core @ag-ui/core @ag-ui/client @copilotkit/runtime
   ```

   **Yarn**:

   ```bash
   yarn add @ag-ui/mastra @mastra/client-js @mastra/core @ag-ui/core @ag-ui/client @copilotkit/runtime
   ```

   **Bun**:

   ```bash
   bun add @ag-ui/mastra @mastra/client-js @mastra/core @ag-ui/core @ag-ui/client @copilotkit/runtime
   ```

   Dans votre fichier `src/mastra/index.ts`, enregistrez la route de chat :

   ```typescript
   import { Mastra } from '@mastra/core/mastra'
   import { registerCopilotKit } from '@ag-ui/mastra/copilotkit'
   // Rest of the imports...

   export const mastra = new Mastra({
     // Rest of the configuration...
     server: {
       cors: {
         origin: '*',
         allowMethods: ['*'],
         allowHeaders: ['*'],
       },
       apiRoutes: [
         registerCopilotKit({
           path: '/copilotkit',
           resourceId: 'weatherAgent',
         }),
       ],
     },
   })
   ```

   Cela expose les Agents de votre instance Mastra à l’adresse `/copilotkit` dans un format compatible avec CopilotKit. Le frontend choisit l’Agent auquel parler avec la prop `agent` présentée ci-dessous. Ajoutez la configuration CORS pour que le frontend CopilotKit puisse accéder au serveur Mastra. Pour les déploiements en production, restreignez les origines CORS à votre domaine frontend.

3. Exécutez le serveur Mastra avec la commande suivante :

   **npm**:

   ```bash
   npm run dev
   ```

   **pnpm**:

   ```bash
   pnpm run dev
   ```

   **Yarn**:

   ```bash
   yarn dev
   ```

   **Bun**:

   ```bash
   bun run dev
   ```

   Par défaut, le serveur Mastra s’exécute sur `http://localhost:4111`. Laissez ce serveur en cours d’exécution pendant la configuration du frontend CopilotKit.

4. Remontez d’un répertoire jusqu’à la racine de votre projet.

   ```bash
   cd ..
   ```

   Créez un projet Next.js nommé `my-copilot-app` :

   **npm**:

   ```bash
   npx create-next-app@latest my-copilot-app
   ```

   **pnpm**:

   ```bash
   pnpm dlx create-next-app@latest my-copilot-app
   ```

   **Yarn**:

   ```bash
   yarn dlx create-next-app@latest my-copilot-app
   ```

   **Bun**:

   ```bash
   bun x create-next-app@latest my-copilot-app
   ```

   Accédez au répertoire de projet Next.js qui vient d’être créé :

   ```bash
   cd my-copilot-app
   ```

5. Installez les packages d’interface CopilotKit, que vous utiliserez pour afficher une interface de chat :

   **npm**:

   ```bash
   npm install @copilotkit/react-ui @copilotkit/react-core
   ```

   **pnpm**:

   ```bash
   pnpm add @copilotkit/react-ui @copilotkit/react-core
   ```

   **Yarn**:

   ```bash
   yarn add @copilotkit/react-ui @copilotkit/react-core
   ```

   **Bun**:

   ```bash
   bun add @copilotkit/react-ui @copilotkit/react-core
   ```

   Ouvrez la route d’accueil de l’application Next.js, généralement `app/page.tsx` ou `src/app/page.tsx`, et remplacez le contenu existant par le code suivant pour configurer une interface de chat CopilotKit de base :

   ```typescript
   import { CopilotChat } from '@copilotkit/react-ui'
   import { CopilotKit } from '@copilotkit/react-core'
   import '@copilotkit/react-ui/styles.css'

   export default function Home() {
     return (
       <CopilotKit runtimeUrl="http://localhost:4111/copilotkit" agent="weatherAgent">
         <CopilotChat
           labels={{
             title: 'Weather Agent',
             initial: 'Hi! 👋 Ask me about the weather, forecasts, and climate.',
           }}
         />
       </CopilotKit>
     )
   }
   ```

   La prop `agent` désigne l’Agent Mastra vers lequel router. Elle doit correspondre à une clé de la map `agents` de votre instance Mastra.

6. Vérifiez que le serveur Mastra et le frontend CopilotKit sont tous deux en cours d’exécution. Démarrez le serveur de développement Next.js :

   **npm**:

   ```bash
   npm run dev
   ```

   **pnpm**:

   ```bash
   pnpm run dev
   ```

   **Yarn**:

   ```bash
   yarn dev
   ```

   **Bun**:

   ```bash
   bun run dev
   ```

   Ouvrez l’application dans votre navigateur et conversez avec votre Agent.

Votre frontend CopilotKit communique maintenant avec un serveur d’Agents Mastra autonome.

## Options d’interface de chat

`CopilotChat` affiche un chat intégré sur toute la hauteur. CopilotKit fournit deux autres surfaces prêtes à l’emploi qui partagent les mêmes props :

- `CopilotSidebar` : un panneau réductible ancré sur le côté de votre application.
- `CopilotPopup` : un bouton flottant qui ouvre une fenêtre de chat.

Remplacez le composant pour changer de surface. Les trois se connectent via le même Provider `CopilotKit` :

```typescript
import { CopilotSidebar } from '@copilotkit/react-ui'
import { CopilotKit } from '@copilotkit/react-core'
import '@copilotkit/react-ui/styles.css'

export default function Home() {
  return (
    <CopilotKit runtimeUrl="http://localhost:4111/copilotkit" agent="weatherAgent">
      <CopilotSidebar
        labels={{
          title: 'Weather Agent',
          initial: 'Hi! 👋 Ask me about the weather.',
        }}
      />
      {/* your app */}
    </CopilotKit>
  )
}
```

Pour des interfaces de chat entièrement personnalisées, où vous fournissez vos propres composants, consultez le [guide d’interface headless de CopilotKit](https://docs.copilotkit.ai/).

## Contrôle et interactivité de l’application

Au-delà du rendu de la sortie de l’Agent comme interface, consultez l’[interface générative](https://mastra.zisheng.pro/fr/guides/build-your-ui/copilotkit/generative-ui), CopilotKit permet à l’Agent d’agir sur votre application et de faire une pause pour l’utilisateur. Les deux modèles s’exécutent avec la même configuration Mastra.

### Tools frontend

Donnez à l’Agent la possibilité d’agir sur votre application. Enregistrez le Tool dans le frontend avec `useFrontendTool` ; le `handler` s’exécute dans le navigateur lorsque l’Agent l’appelle :

```tsx
import { CopilotChat } from '@copilotkit/react-ui'
import { CopilotKit, useFrontendTool } from '@copilotkit/react-core'

function Chat() {
  useFrontendTool({
    name: 'colorChangeTool',
    description: 'Changes the background color',
    parameters: [
      { name: 'color', type: 'string', description: 'The color to change to', required: true },
    ],
    handler: ({ color }) => {
      document.body.style.setProperty('--background', color)
    },
  })

  return <CopilotChat labels={{ title: 'Background Color Changer' }} />
}

export default function Page() {
  return (
    <CopilotKit runtimeUrl="http://localhost:4111/copilotkit" agent="bgColorAgent">
      <Chat />
    </CopilotKit>
  )
}
```

L’Agent Mastra correspondant est un Agent standard auquel il est demandé d’appeler `colorChangeTool` avec la couleur demandée.

### Human-in-the-loop

Mettez l’Agent en pause en cours d’exécution et attendez que l’utilisateur approuve, modifie ou rejette avant de poursuivre. Utilisez `useHumanInTheLoop` : sa fonction `render` reçoit un callback `respond`, et l’exécution de l’Agent reste suspendue jusqu’à son appel.

```tsx
import { CopilotChat } from '@copilotkit/react-ui'
import { CopilotKit, useHumanInTheLoop } from '@copilotkit/react-core'
import { StepsFeedback } from '@/components/steps-feedback'

function Chat() {
  useHumanInTheLoop({
    name: 'generate_task_steps',
    description: 'Generates a list of steps for the user to perform',
    parameters: [
      {
        name: 'steps',
        type: 'object[]',
        attributes: [
          { name: 'description', type: 'string' },
          { name: 'status', type: 'string', enum: ['enabled', 'disabled', 'executing'] },
        ],
      },
    ],
    available: 'enabled',
    // `respond` resumes the agent with the user's edited selection.
    render: ({ args, respond, status }) => (
      <StepsFeedback args={args} respond={respond} status={status} />
    ),
  })

  return <CopilotChat labels={{ title: 'Planning Agent' }} />
}

export default function Page() {
  return (
    <CopilotKit runtimeUrl="http://localhost:4111/copilotkit" agent="planningAgent">
      <Chat />
    </CopilotKit>
  )
}
```

Dans `StepsFeedback`, permettez à l’utilisateur d’activer ou désactiver des étapes, puis appelez `respond({ accepted: true, steps })` pour reprendre l’Agent, ou `respond({ accepted: false })` pour rejeter. L’Agent lit la valeur retournée et poursuit en conséquence. Consultez le composant complet dans le [UI Dojo](https://ui-dojo.mastra.ai/).

L’exemple ci-dessus utilise un Tool client : l’Agent appelle `generate_task_steps` et le frontend y répond avec `respond`. Mastra peut également effectuer une pause sur le serveur, en suspendant un appel de Tool avant son exécution afin qu’une personne l’approuve ou fournisse une entrée. Pour cette approche, consultez le guide Mastra d’[approbation d’Agent](https://mastra.zisheng.pro/fr/docs/agents/agent-approval) côté backend et la référence CopilotKit de [`useHumanInTheLoop`](https://docs.copilotkit.ai/reference/hooks/useHumanInTheLoop) côté frontend.

## Options de configuration

Utilisez ces options `registerCopilotKit()` pour les points d’intégration courants :

| Option           | Utilisation                                                                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `path`           | Définir le chemin de route, tel que `/copilotkit`.                                                                                                |
| `resourceId`     | Définir la portée de la mémoire Mastra pour les conversations.                                                                                    |
| `cors`           | Configurer CORS par route en plus de `server.cors`.                                                                                               |
| `setContext`     | Renseigner le contexte de requête avant l’exécution des Agents, par exemple l’authentification ou des identifiants de ressources par utilisateur. |
| `agents`         | Fournir des Agents AG-UI préconstruits au lieu des Agents enregistrés sur l’instance Mastra.                                                      |
| `tracingOptions` | Transmettre les options de tracing Mastra à chaque exécution d’Agent.                                                                             |

Par défaut, l’endpoint expose tous les Agents enregistrés sur l’instance Mastra et le frontend en choisit un avec la prop `agent`. Les autres options de runtime CopilotKit sont transmises au runtime sous-jacent. Consultez par exemple l’[interface générative ouverte](https://mastra.zisheng.pro/fr/guides/build-your-ui/copilotkit/generative-ui) pour `mcpApps`.

## Déploiement

Lorsque vous déployez votre serveur Mastra avec CopilotKit, vous devez exclure `@copilotkit/runtime` du bundle. Ce package contient des dépendances incompatibles avec le regroupement et provoquera des erreurs 500 s’il est inclus.

> **Remarque:** Ce problème ne survient pas en développement avec `mastra dev`, car il ne requiert pas de regroupement. Toutefois, toute personne qui exécute `mastra build` pour un déploiement rencontrera ce problème.

Ajoutez le package `@copilotkit/runtime` à la configuration des externals de votre bundler :

```typescript
export const mastra = new Mastra({
  bundler: {
    externals: ['@copilotkit/runtime'],
  },
})
```