Agent Client Protocol

Mastra prend en charge l’Agent Client Protocol (ACP) pour exécuter des agents de programmation compatibles ACP depuis un Agent Mastra. Utilisez @mastra/acp pour encapsuler un processus d’agent de programmation comme Tool Mastra ou comme sous-agent.

ACP est utile avec des agents de programmation comme Claude Code, Amp, Codex ou tout autre exécutable qui implémente ACP via l’entrée et la sortie standard.

Quand utiliser ACP

• Un Agent Mastra doit déléguer l’inspection de code, la modification de code ou des tâches de dépôt à un agent de programmation externe.
• Un processus d’agent compatible ACP doit rester actif entre les appels pour conserver le contexte de la session.
• Un Agent parent a besoin de la sortie en temps réel d’un agent de programmation pendant l’exécution de la tâche.
• Un agent compatible ACP doit afficher des demandes d’autorisation avant de lire ou d’écrire des fichiers, ou d’exécuter des actions.
• L’accès aux fichiers doit passer par l’abstraction Workspace de Mastra plutôt que par un accès direct limité au processus.

Fonctionnement d’ACP

@mastra/acp démarre la commande d’agent ACP configurée comme processus enfant et communique avec elle au moyen de JSON délimité par des retours à la ligne via l’entrée et la sortie standard.

Le déroulement est le suivant :

1. Configurez command, args et les paramètres de connexion facultatifs.
2. @mastra/acp lance le processus d’agent ACP lors de sa première utilisation.
3. Le client envoie les requêtes ACP initialize et session/new.
4. Mastra envoie la tâche utilisateur à l’agent ACP avec session/prompt.
5. L’agent ACP renvoie à Mastra les mises à jour de session et les fragments de messages sous forme de flux.
6. Mastra retourne la sortie mise en mémoire tampon ou émet des fragments en flux, ou gère les entrées d’autorisation.
7. La connexion ACP arrête le processus après le prompt lorsque persistSession vaut false. Par défaut, AcpAgent peut conserver un processus réutilisable actif entre les appels.

Pendant l’exécution, le client ACP gère également les demandes d’autorisation et les opérations sur les fichiers. Les lectures et écritures de fichiers passent par le Workspace de Mastra ; l’agent ACP opère donc dans le Workspace que vous fournissez.

Premiers pas

Installez @mastra/acp dans un projet qui utilise déjà @mastra/core. Le package requiert @mastra/core version 1.34.0 ou ultérieure.

npm

npm install @mastra/acp

pnpm

pnpm add @mastra/acp

Yarn

yarn add @mastra/acp

Bun

bun add @mastra/acp

@mastra/acp exporte deux API :

• createACPTool() : crée un Tool Mastra qui envoie une chaîne task à un agent ACP et retourne une chaîne output.
• AcpAgent : encapsule un agent ACP comme sous-agent Mastra prenant en charge generate() et stream().

Utiliser ACP comme sous-agent

Utilisez AcpAgent lorsqu’un Agent Mastra parent doit déléguer directement une tâche à un agent de programmation compatible ACP en tant que sous-agent.

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,
  },
})

Consultez la référence AcpAgent pour toutes les options, méthodes et possibilités de configuration.

Utiliser ACP comme Tool

Utilisez createACPTool() lorsque l’Agent Mastra parent doit décider quand appeler l’agent ACP comme Tool.

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,
  },
})

Consultez la référence createACPTool() pour toutes les options et possibilités de configuration.

Sélection du modèle

Les agents ACP peuvent exposer des modèles sélectionnables. Transmettez model dans la configuration ACP pour sélectionner un modèle après la création de la session, ou utilisez AcpAgent.getAvailableModels() et AcpAgent.setModel() pour gérer les modèles à l’exécution.

Consultez les méthodes de gestion des modèles d’AcpAgent pour des exemples.

Cycle de vie de la session

AcpAgent démarre la commande configurée lors de la première utilisation et crée une session ACP. Par défaut, persistSession vaut true, donc le processus enfant reste actif entre les appels. Définissez persistSession: false lorsque chaque prompt doit s’exécuter dans un processus isolé.

Consultez la section cycle de vie de la session AcpAgent pour plus de détails.

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. Transmettez onPermissionRequest lorsque vous avez besoin d’un comportement d’autorisation personnalisé.

Consultez la section gestion des autorisations de createACPTool() pour un exemple complet.

Intégration de Workspace

Les opérations ACP sur les fichiers passent par l’abstraction Workspace de Mastra. AcpAgent peut utiliser une option workspace, et createACPTool() utilise le Workspace Mastra actuel du contexte d’exécution du Tool lorsqu’il est disponible. Sans Workspace, @mastra/acp utilise un Workspace reposant sur LocalFilesystem dans cwd ou process.cwd().

Consultez la section intégration de Workspace d’AcpAgent pour des exemples de Workspace personnalisés.

Ressources associées

• Référence AcpAgent
• Référence createACPTool()
• Référence Agent
• Sous-agents
• Introduction à Agent Client Protocol
• Schéma d’Agent Client Protocol