Présentation des Channels

Ajouté dans : @mastra/core@1.22.0

Les Channels connectent les Agents à des plateformes de messagerie et de collaboration comme Slack, Microsoft Teams, Discord, Telegram, WhatsApp, GitHub et Linear. Lorsqu’un utilisateur envoie un message ou un commentaire sur une plateforme, l’Agent le reçoit, le traite selon son pipeline habituel, puis diffuse la réponse dans la conversation. Mastra utilise le Chat SDK pour cette couche de Channels.

Commencez par la page correspondant à votre plateforme :

• Slack
• Microsoft Teams
• Discord
• Telegram
• WhatsApp
• iMessage

La page Autres plateformes répertorie des plateformes supplémentaires. Au-delà des plateformes indiquées ici, les Channels Mastra fonctionnent avec les adaptateurs compatibles avec le Chat SDK, et le même modèle de configuration Mastra s’applique à tous les adaptateurs.

Quand utiliser les Channels

Utilisez les Channels lorsqu’un Agent doit :

• Rejoindre les utilisateurs sur les plateformes où ils communiquent ou travaillent déjà.
• Répondre sur des plateformes de chat comme Slack, Microsoft Teams, Discord, Telegram et WhatsApp.
• Prendre en charge des Agents multi-utilisateurs avec lesquels plusieurs personnes interagissent dans un Channel ou un thread partagé.
• S’intégrer à des processus de collaboration comme les issues GitHub, les threads de pull request et les commentaires Linear.

Configurer un Agent

Les Channels utilisent des adaptateurs Chat SDK et suivent le même modèle côté Mastra : créez un adaptateur de Channel et ajoutez-le à l’Agent.

src/mastra/agents/your-agent.ts

import { Agent } from '@mastra/core/agent'
import { createSlackAdapter } from '@chat-adapter/slack'

export const yourAgent = new Agent({
  id: 'your-agent',
  name: 'Your Agent',
  instructions: 'You are a helpful assistant.',
  model: 'openai/gpt-5.6-sol',
  channels: {
    adapters: {
      slack: createSlackAdapter(),
    },
  },
})

remarque

Les adaptateurs de Channel nécessitent des variables d’environnement propres au Provider pour les identifiants et la vérification des requêtes, notamment des tokens de bot, des secrets de signature, des identifiants d’application et des tokens de vérification de webhook. Consultez le guide de votre plateforme ou le catalogue des adaptateurs Chat SDK pour connaître les noms exacts des variables.

Nous recommandons de configurer le stockage pour les Channels. Il permet à Mastra de conserver l’état des Channels, les abonnements aux threads, les approbations de Tools et la mémoire entre les redémarrages :

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'
import { yourAgent } from './agents/your-agent'

export const mastra = new Mastra({
  agents: { yourAgent },
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: process.env.DATABASE_URL,
  }),
})

Routes de webhook

Les plateformes transmettent l’activité des Channels à Mastra par l’intermédiaire de webhooks. Un webhook est un point de terminaison HTTP que la plateforme appelle lorsqu’un événement se produit, par exemple un nouveau message, une mention ou la sélection de « Approve » par un utilisateur sur une carte interactive d’approbation de Tool. C’est ainsi que votre Agent reçoit un nouveau message, commence à le traiter et répond dans le même Channel.

Mastra enregistre une route de webhook pour chaque adaptateur configuré et traite la requête à votre place :

/api/agents/<AGENT_ID>/channels/<PLATFORM>/webhook

Par exemple, un adaptateur Slack associé à un Agent dont l’identifiant est your-agent utilise :

/api/agents/your-agent/channels/slack/webhook

Configurez l’URL de webhook, d’événement ou d’interactions de la plateforme afin qu’elle pointe vers ce chemin. Suivez le guide de votre plateforme ou la documentation du Chat SDK.

Pendant le développement local, les webhooks de la plateforme ont besoin d’une URL publique pour atteindre votre serveur local. Utilisez un tunnel comme cloudflared ou ngrok afin d’exposer votre serveur, qui utilise localhost:4111 par défaut :

npm

npx cloudflared tunnel --url http://localhost:4111

pnpm

pnpm dlx cloudflared tunnel --url http://localhost:4111

Yarn

yarn dlx cloudflared tunnel --url http://localhost:4111

Bun

bun x cloudflared tunnel --url http://localhost:4111

Utilisez l’URL publique générée comme URL de base des chemins de webhook, par exemple https://abc123.trycloudflare.com/api/agents/your-agent/channels/slack/webhook.

remarque

Les URL de tunnel sont destinées au développement local. Après avoir déployé le serveur Mastra, remplacez l’URL de webhook, d’événement ou d’interactions de la plateforme par votre URL de production.

Contexte du thread

Lorsqu’un utilisateur mentionne l’Agent au milieu d’une conversation dans le thread d’un Channel, l’Agent peut ne pas disposer du contexte précédent. Par défaut, Mastra récupère les 10 derniers messages de la plateforme lors de la première mention.

1. Lors de la première mention dans un thread, l’Agent récupère les messages récents de la plateforme.
2. Ces messages sont ajoutés avant celui de l’utilisateur afin de fournir le contexte de la conversation.
3. Après avoir répondu, l’Agent s’abonne au thread et dispose de l’historique complet grâce à la mémoire Mastra.
4. Les messages suivants du thread ne déclenchent pas une nouvelle récupération depuis la plateforme.

Définissez threadContext: { maxMessages: 0 } pour désactiver ce comportement. Cette option s’applique uniquement aux threads qui ne sont pas des messages directs.

Mastra ajoute également un court message système qui indique à l’Agent le Channel et la plateforme d’origine de la requête, par exemple si le message provient d’un message direct ou d’un Channel public. Définissez threadContext: { addSystemMessage: false } pour ne pas l’ajouter.

Approbation des Tools

Les Tools dotés de requireApproval: true s’affichent sous forme de cartes interactives avec les boutons Approve et Deny :

src/mastra/tools/delete-file.ts

import { promises as fs } from 'node:fs'
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const deleteFile = createTool({
  id: 'delete-file',
  description: 'Delete a file from the system',
  inputSchema: z.object({
    path: z.string().describe('Path to the file to delete'),
  }),
  requireApproval: true,
  execute: async ({ path }) => {
    await fs.unlink(path)
    return { deleted: path }
  },
})

Lorsque l’Agent appelle ce Tool, les utilisateurs voient une carte avec le nom du Tool, ses arguments et les actions Approve et Deny. Le Tool ne s’exécute qu’après approbation.

Définissez toolDisplay: 'text' sur un adaptateur afin d’afficher les appels de Tools sous forme de texte brut plutôt que de cartes interactives. En mode 'hidden', autoResumeSuspendedTools peut reprendre les Tools suspendus lorsqu’un message ultérieur de l’utilisateur arrive dans le même thread. Cette fonctionnalité nécessite la mémoire. Le mode masqué supprime uniquement les boutons d’approbation.

Formatage des réponses

Par défaut, les réponses des Agents sont publiées en Markdown. Les plateformes qui proposent un rendu Markdown natif, comme Slack, affichent directement le texte en gras, les liens et les tableaux. Les autres plateformes convertissent le Markdown dans leur propre format. Les Agents écrivent du Markdown standard, qui s’affiche correctement partout et de la même façon que dans Studio.

Définissez textFormat: 'plain' sur un adaptateur pour publier plutôt les réponses sous forme de texte brut littéral :

src/mastra/agents/your-agent.ts

channels: {
  adapters: {
    slack: {
      adapter: createSlackAdapter(),
      textFormat: 'plain',
    },
  },
},

Utilisez cette solution de repli si votre Agent est invité à produire un dialecte propre à une plateforme, comme le mrkdwn de Slack, plutôt que du Markdown standard. Si vous avez ajouté de telles instructions au prompt pour contourner l’affichage littéral du Markdown, supprimez-les. Par défaut, le Markdown standard est désormais rendu nativement. textFormat affecte uniquement le texte de la réponse finale. Les cartes de Tools, les messages d’erreur et le texte diffusé nativement ne sont pas concernés.

Prise en compte de plusieurs utilisateurs

Dans les conversations de groupe, Mastra préfixe chaque message avec le nom et l’identifiant de plateforme de son expéditeur afin que l’Agent puisse distinguer les différents interlocuteurs :

[Alice (@U123ABC)]: Can you help me with this?
[Bob (@U456DEF)]: I have a question too.

Contenu multimodal

Les modèles comme Gemini peuvent traiter nativement les images, la vidéo et l’audio. Combinez inlineMedia et inlineLinks afin que les utilisateurs puissent partager des contenus riches avec votre Agent sur différentes plateformes :

src/mastra/agents/vision-agent.ts

import { Agent } from '@mastra/core/agent'
import { createDiscordAdapter } from '@chat-adapter/discord'

export const visionAgent = new Agent({
  id: 'vision-agent',
  name: 'Vision Agent',
  instructions: 'You can see images, watch videos, and listen to audio.',
  model: 'google/gemini-2.5-flash',
  channels: {
    adapters: {
      discord: createDiscordAdapter(),
    },
    inlineMedia: ['image/*', 'video/*', 'audio/*'],
    inlineLinks: [
      { match: 'youtube.com', mimeType: 'video/*' },
      { match: 'youtu.be', mimeType: 'video/*' },
      'imgur.com',
    ],
  },
})

Avec cette configuration :

• Un utilisateur importe une capture d’écran et l’Agent décrit ce qu’il voit.
• Un utilisateur importe une vidéo .mp4 et l’Agent la résume.
• Un utilisateur colle un lien YouTube et l’Agent regarde la vidéo puis en discute.
• Un utilisateur colle un lien imgur et l’Agent voit directement l’image.

Par défaut, seules les images sont envoyées en ligne (inlineMedia: ['image/*']). Les types non pris en charge sont décrits sous forme de résumés textuels afin que l’Agent ait connaissance du fichier sans provoquer d’échec avec les modèles qui les refusent. Consultez la référence des Channels pour connaître tous les modèles inlineMedia, et la référence d’inlineLinks pour la correspondance des domaines, la détection HEAD et l’attribution forcée des types MIME.

Déploiement serverless

Sur les plateformes serverless comme Vercel, chaque requête s’exécute dans une instance distincte et de courte durée. Pour fonctionner de manière fiable dans cet environnement, les Channels nécessitent deux éléments : un moyen de maintenir la fonction active pendant que l’Agent répond, et un système pub/sub partagé pour coordonner les instances.

Maintenir la fonction active avec waitUntil

Le webhook d’un Channel renvoie immédiatement une réponse 200, puis l’Agent s’exécute en arrière-plan pour publier sa réponse. Sur la plupart des plateformes serverless, la fonction est figée dès qu’elle répond, ce qui interrompt l’exécution avant la réponse de l’Agent. Transmettez une fonction waitUntil afin que la plateforme maintienne l’instance active jusqu’à la fin de l’exécution.

Sur Vercel, transmettez waitUntil depuis @vercel/functions :

src/mastra/agents/your-agent.ts

import { Agent } from '@mastra/core/agent'
import { createSlackAdapter } from '@chat-adapter/slack'
import { waitUntil } from '@vercel/functions'

export const yourAgent = new Agent({
  id: 'your-agent',
  name: 'Your Agent',
  instructions: 'You are a helpful assistant.',
  model: 'openai/gpt-5.6-sol',
  channels: {
    adapters: {
      slack: createSlackAdapter(),
    },
    waitUntil,
  },
})

Vercel et AWS Lambda nécessitent waitUntil, car ils figent la fonction dès que la réponse est envoyée. Cloudflare Workers et Netlify Functions sont détectés automatiquement à partir du contexte de la requête et n’en ont donc pas besoin. Pour les environnements d’exécution dans lesquels waitUntil se trouve dans le contexte de la requête sans être détecté automatiquement, utilisez resolveWaitUntil. Consultez la référence des Channels pour en savoir plus.

Coordonner les instances avec un système pub/sub partagé

Les Channels acheminent les messages par le pipeline de signaux de l’Agent, et chaque exécution obtient un bail sur son thread afin qu’une seule exécution contrôle la conversation à la fois.

Le système pub/sub en mémoire par défaut ne peut pas franchir les limites des instances. Dans un environnement serverless, un message de suivi peut donc être acheminé vers une autre instance que celle qui exécute l’Agent.

Sans système pub/sub partagé, cette instance ne peut pas atteindre l’exécution active et démarre la sienne. L’exécution d’origine reste intacte et le thread est traité deux fois.

Configurez dans l’instance Mastra un système pub/sub partagé fondé sur Redis Streams afin de coordonner les baux et les signaux entre les instances :

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { RedisStreamsPubSub } from '@mastra/redis-streams'
import { yourAgent } from './agents/your-agent'

export const mastra = new Mastra({
  agents: { yourAgent },
  pubsub: new RedisStreamsPubSub({
    url: process.env.REDIS_URL,
    keyPrefix: 'mastra:my-app',
  }),
})

L’intégration Redis gérée de Vercel et Upstash Redis conviennent toutes deux. Pour savoir dans quels cas un système pub/sub distribué est nécessaire, consultez le guide PubSub et la référence de RedisStreamsPubSub.

Voir aussi

• Référence des Channels
• Channels d’AgentController
• 📹 Atelier sur les Channels Mastra