> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# Agent Client Protocol

Mastra prend en charge l’[Agent Client Protocol (ACP)](https://agentclientprotocol.com/overview/introduction) 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**:

```bash
npm install @mastra/acp
```

**pnpm**:

```bash
pnpm add @mastra/acp
```

**Yarn**:

```bash
yarn add @mastra/acp
```

**Bun**:

```bash
bun add @mastra/acp
```

`@mastra/acp` exporte deux API :

- [`createACPTool()`](https://mastra.zisheng.pro/fr/reference/acp/create-acp-tool) : crée un Tool Mastra qui envoie une chaîne `task` à un agent ACP et retourne une chaîne `output`.
- [`AcpAgent`](https://mastra.zisheng.pro/fr/reference/acp/acp-agent) : 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.

```typescript
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](https://mastra.zisheng.pro/fr/reference/acp/acp-agent) 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.

```typescript
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()](https://mastra.zisheng.pro/fr/reference/acp/create-acp-tool) 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](https://mastra.zisheng.pro/fr/reference/acp/acp-agent) 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](https://mastra.zisheng.pro/fr/reference/acp/acp-agent) 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()](https://mastra.zisheng.pro/fr/reference/acp/create-acp-tool) 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](https://mastra.zisheng.pro/fr/reference/acp/acp-agent) pour des exemples de Workspace personnalisés.

## Ressources associées

- [Référence AcpAgent](https://mastra.zisheng.pro/fr/reference/acp/acp-agent)
- [Référence createACPTool()](https://mastra.zisheng.pro/fr/reference/acp/create-acp-tool)
- [Référence Agent](https://mastra.zisheng.pro/fr/reference/agents/agent)
- [Sous-agents](https://mastra.zisheng.pro/fr/docs/capabilities/subagents)
- [Introduction à Agent Client Protocol](https://agentclientprotocol.com/overview/introduction)
- [Schéma d’Agent Client Protocol](https://agentclientprotocol.com/protocol/schema)