Aller au contenu principal

Utiliser CopilotKit

CopilotKit 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. 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, ainsi que le déploiement du même Agent dans des canaux de messagerie comme Slack.

Consultez la documentation CopilotKit 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.

Consultez le « UI Dojo » de Mastra pour voir des exemples concrets d’intégration de CopilotKit avec Mastra.

Guide d’intégration
Lien direct vers 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 :

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

    Initialisez votre serveur Mastra :

    npx 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éé :

    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 install @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 :

    src/mastra/index.ts
    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 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.

    cd ..

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

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

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

    cd my-copilot-app

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

    npm install @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 :

    app/page.tsx
    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 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
Lien direct vers 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 :

app/page.tsx
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.

Contrôle et interactivité de l’application
Lien direct vers 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, 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
Lien direct vers 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 :

app/page.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
Lien direct vers 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.

app/page.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.

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 côté backend et la référence CopilotKit de useHumanInTheLoop côté frontend.

Options de configuration
Lien direct vers Options de configuration

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

OptionUtilisation
pathDéfinir le chemin de route, tel que /copilotkit.
resourceIdDéfinir la portée de la mémoire Mastra pour les conversations.
corsConfigurer CORS par route en plus de server.cors.
setContextRenseigner le contexte de requête avant l’exécution des Agents, par exemple l’authentification ou des identifiants de ressources par utilisateur.
agentsFournir des Agents AG-UI préconstruits au lieu des Agents enregistrés sur l’instance Mastra.
tracingOptionsTransmettre 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 pour mcpApps.

Déploiement
Lien direct vers 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 :

src/mastra/index.ts
export const mastra = new Mastra({
  bundler: {
    externals: ['@copilotkit/runtime'],
  },
})
On this page