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

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

## Exemple d'utilisation

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

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

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 :

```typescript
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. (Default: `[]`)

**env** (`Record<string, string>`): Variables d'environnement à fusionner avec l'environnement du processus actuel lors du lancement du processus ACP.

**cwd** (`string`): 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. (Default: `process.cwd()`)

**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`): 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. (Default: `true`)

**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.

```typescript
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`.

```typescript
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.

```typescript
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.

```typescript
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 :

```typescript
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 :

```typescript
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 :

```typescript
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](https://mastra.zisheng.pro/fr/docs/agents/acp)
- [Référence de createACPTool()](https://mastra.zisheng.pro/fr/reference/acp/create-acp-tool)
- [Référence d'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)