createACPTool()

La fonction createACPTool() crée un Tool Mastra qui envoie une chaîne task à un Agent de programmation compatible avec l'Agent Client Protocol (ACP) et renvoie la réponse ACP finale sous la forme output. Utilisez-la lorsqu'un Agent parent doit décider à quel moment appeler l'Agent ACP en tant que Tool.

Si vous souhaitez plutôt enregistrer l'Agent ACP en tant que sous-Agent Mastra, utilisez la classe AcpAgent.

Exemple d'utilisation

Créez un Tool de modification de code et enregistrez-le auprès d'un Agent parent :

src/mastra/agents/code-supervisor.ts

import { createACPTool } from '@mastra/acp'
import { Agent } from '@mastra/core/agent'

const codeAgentTool = createACPTool({
  id: 'code-agent',
  description: 'Use an ACP-compatible coding agent to inspect and edit code',
  command: 'acp-agent',
  args: ['--stdio'],
  cwd: process.cwd(),
})

export const codeSupervisor = new Agent({
  id: 'code-supervisor',
  name: 'Code Supervisor',
  instructions: 'Use the code-agent tool when a task requires repository inspection or code edits.',
  model: 'openai/gpt-5.6-sol',
  tools: {
    codeAgentTool,
  },
})

Paramètres

id:

string

Identifiant unique du Tool Mastra.

description:

string

Description présentée au modèle lorsqu'il peut appeler ce Tool.

command:

string

Exécutable de l'Agent ACP à lancer.

args?:

string[]

= []

Arguments transmis à l'exécutable de l'Agent ACP.

env?:

Record<string, string>

Variables d'environnement à fusionner avec l'environnement du processus actuel lors du lancement du processus ACP.

cwd?:

string

= process.cwd()

Répertoire de travail du processus et de la session ACP. Également utilisé comme chemin de base par défaut du système de fichiers local.

session?:

Partial<NewSessionRequest>

Options de création de la session ACP. Utilise par défaut cwd ou process.cwd(), ainsi qu’une liste vide de serveurs MCP.

initialize?:

Partial<InitializeRequest>

Options d'initialisation d'ACP. Utilise par défaut les informations du client Mastra, la version actuelle du protocole ACP et les fonctionnalités de lecture/écriture du système de fichiers.

authMethodId?:

string

Identifiant de la méthode d'authentification ACP à invoquer après l'initialisation et avant la création de la session.

persistSession?:

boolean

= true

Indique si la connexion ACP créée pour l'exécution d'un Tool se déconnecte après le prompt. Définissez cette option sur false pour arrêter le processus à la fin de chaque prompt.

onPermissionRequest?:

(request: RequestPermissionRequest) => Promise<RequestPermissionResponse>

Callback invoqué lorsque l'Agent ACP demande une autorisation. Par défaut, la première option d'autorisation est sélectionnée, ou la demande est annulée si aucune option n'est disponible.

createClient?:

(defaultClient: Client) => Client

Personnalise le client ACP utilisé pour répondre aux requêtes de l'Agent. Reçoit le client par défaut afin de pouvoir l'encapsuler ou l'étendre, par exemple avec des gestionnaires extMethod et extNotification.

workspace?:

Workspace

Option Workspace provenant des options de connexion ACP partagées. Pendant l'exécution du Tool, createACPTool() transmet le Workspace Mastra actuel issu du contexte d'exécution lorsqu'il est disponible ; sinon, la connexion ACP utilise un Workspace de système de fichiers local. Utilisez AcpAgent lorsque vous devez fournir une instance de Workspace explicite.

model?:

ModelId

Identifiant du modèle à sélectionner après la création de la session ACP au moyen de la méthode ACP session/set_model.

Schéma d'entrée

task:

string

Tâche à envoyer à l'Agent ACP.

Schéma de sortie

output:

string

Sortie textuelle finale renvoyée par l'Agent ACP.

Schéma de suspension et de reprise

createACPTool() définit des schémas de suspension et de reprise pour les payloads de demandes d'autorisation. Les décisions d'autorisation sont renvoyées par l'intermédiaire de onPermissionRequest ; par défaut, @mastra/acp sélectionne la première option renvoyée par l'Agent ACP ou annule la demande si aucune option n'est disponible.

Payload de suspension

permissionRequest:

{ title: string; options: { optionId: string; name: string }[] }

Titre de la demande d'autorisation et options sélectionnables renvoyés par l'Agent ACP.

Payload de reprise

optionId?:

string

Identifiant de l'option d'autorisation à sélectionner lors de la reprise avec outcome: "selected".

outcome?:

"selected" | "cancelled"

Décision d'autorisation utilisée pour poursuivre ou annuler la requête ACP.

Cycle de vie de la session

Chaque exécution du Tool crée une connexion ACP et démarre la command configurée. Elle initialise le client ACP et crée une session ACP avant d'envoyer la task au moyen de la méthode ACP session/prompt.

Par défaut, persistSession vaut true pour la connexion ACP créée pendant l'exécution du Tool. Définissez persistSession: false lorsque le processus ACP doit s'arrêter dès que ce prompt est terminé.

Utilisez AcpAgent lorsque vous avez besoin d'une instance de sous-Agent ACP réutilisable offrant un contrôle explicite du cycle de vie de la session entre les appels.

Gestion des autorisations

Les Agents ACP peuvent demander au client de choisir une option d'autorisation avant de poursuivre. Par défaut, @mastra/acp sélectionne la première option renvoyée par l'Agent ACP ou annule la demande si aucune option n'est disponible.

Transmettez onPermissionRequest pour examiner la requête et renvoyer votre propre réponse d'autorisation :

src/mastra/agents/code-agent.ts

import { createACPTool } from '@mastra/acp'

export const codeAgentTool = createACPTool({
  id: 'code-agent',
  description: 'Use an ACP-compatible coding agent',
  command: 'acp-agent',
  args: ['--stdio'],
  async onPermissionRequest(request) {
    const allowOption = request.options.find(option => option.name === 'Allow')

    if (!allowOption) {
      return { outcome: { outcome: 'cancelled' } }
    }

    return {
      outcome: {
        outcome: 'selected',
        optionId: allowOption.optionId,
      },
    }
  },
})

Utilisez ce callback pour appliquer une politique locale ou examiner le titre de l'autorisation. Il peut également acheminer la décision vers votre propre processus d'approbation.

Méthodes d'extension

Certains Agents ACP appellent des méthodes d'extension personnalisées sur le client, en dehors de l'ensemble standard des requêtes ACP. Le client par défaut rejette les méthodes inconnues avec une erreur « Method not found », ce qui peut interrompre le tour de l'Agent.

Transmettez createClient pour étendre ou remplacer le client par défaut. Le callback reçoit le client par défaut et renvoie le client utilisé pour la connexion :

src/mastra/agents/code-agent.ts

import { createACPTool } from '@mastra/acp'

export const codeAgentTool = createACPTool({
  id: 'code-agent',
  description: 'Use an ACP-compatible coding agent',
  command: 'acp-agent',
  args: ['--stdio'],
  createClient: defaultClient =>
    Object.assign(defaultClient, {
      async extMethod(method: string, params: Record<string, unknown>) {
        return {}
      },
      async extNotification(method: string, params: Record<string, unknown>) {},
    }),
})

Renvoyez une implémentation Client entièrement personnalisée lorsque vous devez également modifier les gestionnaires standard. Le type Client est réexporté depuis @mastra/acp.

Voir aussi

• Documentation d'Agent Client Protocol
• Référence de la classe AcpAgent
• Référence des Tools
• Introduction à Agent Client Protocol
• Schéma d'Agent Client Protocol