ToolProvider

L'interface ToolProvider définit la manière dont l'éditeur découvre et résout les tools d'intégration provenant de plateformes externes. Mastra comprend deux implémentations intégrées : ComposioToolProvider et ArcadeToolProvider.

Consultez les tools de l'Editor pour configurer le Provider et découvrir le workflow de Studio. Consultez la configuration des tools pour en savoir plus sur les sélections enregistrées et le comportement de résolution.

Interface ToolProvider

Les Providers exposent des métadonnées ainsi que les anciennes méthodes de découverte et de résolution. Les intégrations Agent Builder peuvent également implémenter les méthodes VNext facultatives de catalogue, de connexion, d'autorisation et d'état de santé.

info:

ToolProviderInfo

Identifiant, nom et description du Provider.

displayName?:

string

Nom facultatif affiché dans le sélecteur de tools. La valeur par défaut est info.name.

capabilities?:

ToolProviderCapabilities

Capacités statiques de connexion et de révocation. Requises pour les Providers VNext.

defaultScope?:

'per-author' | 'caller-supplied'

Portée par défaut de l'identité de connexion. La valeur par défaut est 'per-author' en cas d'omission.

listToolkits()?:

() => Promise<ToolProviderListResult<ToolProviderToolkit>>

Répertorie les toolkits disponibles au moyen de l'ancienne interface.

listTools(params?):

(params?: ListToolProviderToolsOptions) => Promise<ToolProviderListResult<ToolProviderToolInfo>>

Répertorie les tools avec des filtres facultatifs de toolkit, de recherche et de pagination.

getToolSchema(slug)?:

(slug: string) => Promise<Record<string, unknown> | null>

Renvoie le schéma d'entrée d'un tool au moyen de l'ancienne interface.

resolveTools(slugs, configs?, options?):

(slugs: string[], configs?: Record<string, StorageToolConfig>, options?: ResolveToolProviderToolsOptions) => Promise<Record<string, ToolAction>>

Résout les anciennes sélections de tools en tools Mastra exécutables.

listToolkitsVNext()?:

() => Promise<ListToolkitsResult>

Répertorie les toolkits autorisés pour Agent Builder et Editor.

listToolsVNext(options?)?:

(options?: ListToolsOpts) => Promise<ListToolsResult>

Répertorie les tools autorisés avec des options de toolkit, de recherche et de pagination.

resolveToolsVNext(options)?:

(options: ResolveToolsOpts) => Promise<Record<string, ToolAction>>

Résout les tools pour un ensemble de slugs et une connexion autorisée.

authorize(options)?:

(options: AuthorizeOpts) => Promise<{ url: string; authId: string }>

Démarre un flux d'autorisation.

listConnectionFields(options)?:

(options: { toolkit: string }) => Promise<ConnectionField[]>

Répertorie les valeurs propres au Provider requises pour autoriser un toolkit.

getAuthStatus(authId)?:

(authId: string) => Promise<AuthFlowStatus>

Renvoie l'état d'un flux d'autorisation.

getConnectionStatus(options)?:

(options: { items: Array<{ connectionId: string; toolkit: string }> }) => Promise<Record<string, { connected: boolean }>>

Vérifie si un lot de connexions est toujours actif.

listConnections(options)?:

(options: ListConnectionsOpts) => Promise<ListConnectionsResult>

Répertorie les connexions existantes d'un Provider pour un utilisateur et un toolkit.

getHealth()?:

() => Promise<ToolProviderHealth>

Renvoie la configuration et l'état d'accessibilité du Provider.

revokeConnection(connectionId)?:

(connectionId: string) => Promise<void>

Révoque une connexion au Provider.

---

ComposioToolProvider

Se connecte à Composio pour accéder à des centaines de tools d'intégration.

Exemple d'utilisation

src/mastra/index.ts

import { MastraEditor } from '@mastra/editor'
import { ComposioToolProvider } from '@mastra/editor/composio'

const editor = new MastraEditor({
  toolProviders: {
    composio: new ComposioToolProvider({
      apiKey: process.env.COMPOSIO_API_KEY!,
    }),
  },
})

Paramètres du constructeur

apiKey:

string

Votre clé API Composio.

allowedToolkits?:

readonly string[]

Liste des slugs de toolkit autorisés. Prend en charge les correspondances exactes et les caractères génériques de suffixe.

allowedTools?:

Readonly<Record<string, readonly string[]>>

Listes des slugs de tools autorisés pour chaque toolkit. Prennent en charge les correspondances exactes et les caractères génériques de préfixe.

defaultScope?:

'per-author' | 'caller-supplied'

= 'per-author'

Portée de l'identité de connexion. La valeur par défaut est per-author.

Slugs des tools

Les tools Composio utilisent des slugs en majuscules : GITHUB_CREATE_ISSUE, SLACK_SEND_MESSAGE.

Authentification

Par défaut, les connexions utilisent la portée par auteur. Définissez defaultScope: 'caller-supplied' pour regrouper les autorisations selon l'identité de l'appelant déterminée à partir de MASTRA_RESOURCE_ID_KEY dans le contexte de la requête. Veillez à ce que chaque requête authentifiée fournisse un identifiant de ressource stable et unique. Lorsque vous utilisez MastraAuthWorkos, configurez mapUserToResourceId afin de définir cette valeur à partir de l'utilisateur authentifié.

Tools de gestion des connexions

Composio fournit des tools permettant de démarrer et de surveiller l'autorisation depuis une conversation avec un agent. Lorsque allowedToolkits est défini, incluez composio pour rendre ces tools disponibles :

src/mastra/index.ts

const editor = new MastraEditor({
  toolProviders: {
    composio: new ComposioToolProvider({
      apiKey: process.env.COMPOSIO_API_KEY!,
      allowedToolkits: ['composio', 'gmail'],
      defaultScope: 'caller-supplied',
    }),
  },
})

Ajoutez uniquement les tools de gestion des connexions dont l'agent a besoin :

Tool	Comportement
COMPOSIO_MANAGE_CONNECTIONS	Crée un lien d'autorisation dans la conversation par l'intermédiaire d'une session appartenant à l'appelant.
COMPOSIO_WAIT_FOR_CONNECTIONS	Attend que l'appelant termine l'autorisation avant que l'agent poursuive.

COMPOSIO_WAIT_FOR_CONNECTIONS est facultatif. Sans ce tool, terminez l'autorisation et revenez à la conversation. Demandez ensuite à l'agent de poursuivre. Le compte connecté reste associé à l'identifiant de ressource de l'appelant pour les requêtes ultérieures.

---

ArcadeToolProvider

Se connecte à Arcade pour accéder à un catalogue de tools sélectionnés avec authentification intégrée.

Exemple d'utilisation

src/mastra/index.ts

import { MastraEditor } from '@mastra/editor'
import { ArcadeToolProvider } from '@mastra/editor/arcade'

const editor = new MastraEditor({
  toolProviders: {
    arcade: new ArcadeToolProvider({
      apiKey: process.env.ARCADE_API_KEY!,
    }),
  },
})

Paramètres du constructeur

apiKey:

string

Votre clé API Arcade.

baseURL?:

string

URL de base personnalisée pour l'API Arcade.

Slugs des tools

Les tools Arcade utilisent le format Toolkit.ToolName : Github.GetRepository, Slack.SendMessage.

Authentification

L'ancien résolveur Arcade utilise resourceId depuis le contexte de la requête lorsqu'il est disponible. Sinon, il se rabat sur le userId fourni, puis sur une identité default partagée. N'utilisez default que pour les intégrations volontairement partagées. Dans les déploiements où les locataires sont isolés, fournissez un resourceId fiable et stable ou un userId explicite. Omettre les deux n'isole pas les appelants.