Classe AcpAgent

La classe AcpAgent encapsule un Agent de programmation compatible avec l'Agent Client Protocol (ACP) sous la forme d'un sous-Agent Mastra. Utilisez-la lorsqu'un Agent Mastra parent doit déléguer l'inspection d'un dépôt et la modification de code. Elle peut également déléguer au sous-Agent d'autres tâches reposant sur ACP.

Si vous souhaitez plutôt que l'Agent parent appelle l'Agent ACP en tant que Tool, utilisez createACPTool().

Exemple d'utilisation

Enregistrez un Agent de programmation compatible ACP dans la map agents d'un Agent parent :

src/mastra/agents/code-supervisor.ts

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

const codeAgent = new AcpAgent({
  id: 'code-agent',
  name: 'Code Agent',
  description: 'An ACP-compatible coding agent that can inspect and edit files',
  command: 'acp-agent',
  args: ['--stdio'],
  cwd: process.cwd(),
})

export const codeSupervisor = new Agent({
  id: 'code-supervisor',
  name: 'Code Supervisor',
  instructions: 'Delegate code editing tasks to the code-agent subagent.',
  model: 'openai/gpt-5.6-sol',
  agents: {
    codeAgent,
  },
})

Pour Claude Code, la prise en charge d'ACP est fournie par le package Bridge @agentclientprotocol/claude-agent-acp. Configurez la commande de l'Agent ACP afin d'exécuter le Bridge, puis sélectionnez un modèle Claude après la création de la session :

src/mastra/agents/claude-code-agent.ts

import { AcpAgent } from '@mastra/acp'

export const claudeCodeAgent = new AcpAgent({
  id: 'claude-code-agent',
  name: 'Claude Code Agent',
  description: 'Use Claude Code through ACP.',
  command: 'npx',
  args: ['@agentclientprotocol/claude-agent-acp'],
  cwd: process.cwd(),
  model: 'claude-sonnet-4-6',
})

Paramètres du constructeur

id:

string

Identifiant unique du sous-Agent.

name?:

string

Nom d'affichage utilisé lors de la délégation de l'Agent. Utilise par défaut id.

description:

string

Description présentée au modèle lorsqu'il peut déléguer à ce sous-Agent.

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 le processus et la session ACP doivent rester actifs après chaque 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. Consultez Méthodes d'extension.

workspace?:

Workspace

Workspace utilisé pour les requêtes ACP de lecture et d'écriture de fichiers. Utilise par défaut un Workspace reposant sur LocalFilesystem à l'emplacement cwd ou process.cwd().

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.

Propriétés

id:

TId

Identifiant en lecture seule du sous-Agent, issu des options du constructeur.

name:

string

Nom d'affichage en lecture seule de ce sous-Agent.

description:

string

Description en lecture seule présentée lorsque l'Agent parent peut déléguer à ce sous-Agent.

connection:

ACPConnection

Connexion ACP en lecture seule utilisée pour démarrer le processus de l'Agent, créer des sessions, envoyer des prompts, diffuser les mises à jour et gérer les modèles.

Méthodes

Génération

generate(messages, options?)

Envoie le prompt à l'Agent ACP, met en mémoire tampon les chunks de texte de la réponse ACP et renvoie un résultat de génération de sous-Agent Mastra.

const result = await codeAgent.generate('Inspect the repository and summarize the test setup')

console.log(result.text)

stream(messages, options?)

Envoie le prompt à l'Agent ACP et renvoie un résultat de flux de sous-Agent Mastra. Les mises à jour ACP agent_message_chunk sont émises sous la forme de chunks Mastra text-delta.

const result = await codeAgent.stream('Refactor the selected module and explain each change')

for await (const chunk of result.fullStream) {
  if (chunk.type === 'text-delta') {
    process.stdout.write(chunk.payload.text)
  }
}

resumeGenerate() et resumeStream() ne sont pas pris en charge et lèvent une erreur lorsqu'ils sont appelés.

Gestion des modèles

getAvailableModels()

Démarre le processus ACP si nécessaire et renvoie la liste des modèles annoncée par la session ACP.

const models = await codeAgent.getAvailableModels()
// [{ modelId: 'claude-sonnet-4-6', name: 'Claude Sonnet' }, ...]

setModel(modelId)

Sélectionne un modèle pour la session ACP active. Si l'Agent ACP annonce les modèles disponibles, l'identifiant du modèle doit correspondre à l'un d'eux.

await codeAgent.setModel('claude-sonnet-4-6')

Cycle de vie de la session

AcpAgent démarre la command configurée lors de la première utilisation et initialise le client ACP. Il crée ensuite une session ACP. Par défaut, persistSession vaut true ; le processus et la session restent donc actifs entre les appels à generate(), stream(), getAvailableModels() et setModel().

Définissez persistSession: false lorsque chaque prompt doit s'exécuter dans un nouveau processus ACP :

src/mastra/agents/code-agent.ts

import { AcpAgent } from '@mastra/acp'

export const codeAgent = new AcpAgent({
  id: 'code-agent',
  description: 'Run one isolated ACP coding task',
  command: 'acp-agent',
  args: ['--stdio'],
  cwd: process.cwd(),
  persistSession: false,
})

Avec persistSession: false, @mastra/acp arrête le processus ACP à la fin de chaque prompt.

Intégration à Workspace

Les opérations ACP sur les fichiers passent par l'abstraction Workspace de Mastra. Si vous ne transmettez pas workspace, @mastra/acp crée un Workspace reposant sur LocalFilesystem et utilise cwd ou process.cwd() comme chemin de base du système de fichiers.

Transmettez un Workspace personnalisé lorsque l'Agent ACP doit lire et écrire au moyen d'une implémentation précise du système de fichiers :

src/mastra/agents/code-agent.ts

import { AcpAgent } from '@mastra/acp'
import { LocalFilesystem, Workspace } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: process.cwd(),
  }),
})

export const codeAgent = new AcpAgent({
  id: 'code-agent',
  description: 'Run coding tasks in a controlled workspace',
  command: 'acp-agent',
  args: ['--stdio'],
  workspace,
})

Utilisez cwd et workspace ensemble lorsque le processus ACP doit démarrer dans un répertoire, mais que les opérations sur les fichiers doivent utiliser une racine de Workspace configurée explicitement.

Gestion des autorisations

Les Agents ACP peuvent demander au client de choisir une option d'autorisation avant de poursuivre. Par défaut, AcpAgent 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 { AcpAgent } from '@mastra/acp'

export const codeAgent = new AcpAgent({
  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.

Voir aussi

• Documentation d'Agent Client Protocol
• Référence de createACPTool()
• Référence d'Agent
• Sous-Agents
• Introduction à Agent Client Protocol
• Schéma d'Agent Client Protocol