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

# Editor

Editor fonctionne comme un CMS pour les Agents Mastra. Les collaborateurs peuvent modifier les instructions et les Tools d’un Agent dans Studio sans accéder au code source ni écrire de code. Ils peuvent tester les modifications avant de les mettre en production.

TypeScript définit les valeurs par défaut de l’Agent. Editor enregistre les modifications séparément au lieu de mettre à jour le code source. Les collaborateurs peuvent ainsi améliorer l’Agent tandis que les développeurs conservent le contrôle de son modèle, de son identité et de son environnement d’exécution.

Un [Studio déployé](https://mastra.zisheng.pro/fr/docs/studio/deployment) rend Editor accessible aux collaborateurs en dehors du développement local.

> **📹 À regarder:** Regardez l’[atelier Mastra Editor](https://www.youtube.com/watch?v=XTjuRoI7t_k\&pp=ygUWbWFzdHJhIGVkaXRvciB3b3Jrc2hvcA%3D%3D) pour suivre une présentation guidée.

## Quand utiliser Editor

Utilisez Editor lorsqu’un Agent est défini dans le code, mais que les personnes responsables de son comportement ne doivent pas modifier le code source. Editor convient particulièrement lorsque les instructions ou les Tools changent souvent et doivent être testés avant d’atteindre les utilisateurs. Si les développeurs prennent en charge chaque modification et publient la configuration de l’Agent avec l’application, conservez plutôt la [configuration de l’Agent dans le code](https://mastra.zisheng.pro/fr/docs/agents/overview).

## Démarrage rapide

Installez `@mastra/editor`. Ce guide de démarrage rapide utilise LibSQL pour stocker les modifications d’Editor :

**npm**:

```bash
npm install @mastra/editor @mastra/libsql
```

**pnpm**:

```bash
pnpm add @mastra/editor @mastra/libsql
```

**Yarn**:

```bash
yarn add @mastra/editor @mastra/libsql
```

**Bun**:

```bash
bun add @mastra/editor @mastra/libsql
```

Ajoutez `MastraEditor` et le stockage à l’instance `Mastra`. Vous pouvez réutiliser un stockage existant au lieu d’ajouter le stockage LibSQL présenté ici.

```typescript
import { Mastra } from '@mastra/core'
import { MastraEditor } from '@mastra/editor'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  agents: {/* existing agents */},
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  editor: new MastraEditor(),
})
```

## Utiliser Editor dans Studio

Dans [Studio](https://mastra.zisheng.pro/fr/docs/studio/overview), ouvrez **Agents**, sélectionnez un Agent, puis **Editor**. Les collaborateurs peuvent mettre à jour les instructions et les Tools de l’Agent selon ses autorisations Editor.

Avec le stockage en base de données, enregistrez les modifications sous forme de brouillon afin de les tester sans affecter l’Agent en production. Publiez le brouillon lorsqu’il est prêt à être utilisé.

## Instructions

La section **Instructions** affiche le prompt système de l’Agent défini dans le code. Les collaborateurs peuvent le remplacer ou ajouter des blocs d’instructions.

Un bloc d’instructions peut inclure des valeurs de la requête actuelle. Par exemple, `{{userName}}` insère un nom fourni par le [contexte de requête](https://mastra.zisheng.pro/fr/docs/server/request-context). Une [condition d’affichage](https://mastra.zisheng.pro/fr/reference/editor/prompt-blocks) peut afficher un bloc uniquement pour un client, un rôle ou un feature flag donné.

### Blocs de prompts

Un bloc de prompt est un texte d’instructions enregistré qui peut être utilisé par plusieurs Agents. Créez-en un sous **Prompts**, publiez-le, puis ouvrez la section **Instructions** d’un Agent et sélectionnez **Add block**.

Par exemple, les Agents chargés de l’assistance, des retours et du suivi des commandes peuvent tous avoir besoin de la même politique de remboursement. Enregistrez cette politique sous forme de bloc de prompt et ajoutez-la à chaque Agent. Lorsqu’elle change, mettez à jour et publiez le bloc une seule fois au lieu de modifier trois Agents.

Lorsqu’un bloc de prompt change, chaque Agent qui référence sa version publiée reçoit la mise à jour. Les modifications du brouillon sont utilisées uniquement pendant l’aperçu et n’affectent donc pas les Agents en production avant la publication du bloc.

Consultez la [référence des blocs de prompts](https://mastra.zisheng.pro/fr/reference/editor/prompt-blocks) pour la syntaxe des modèles, les conditions, les versions et les API.

## Tools

Les Tools permettent à un Agent d’effectuer des actions. Les collaborateurs choisissent parmi les Tools accessibles à Editor, mais ne peuvent pas en implémenter de nouveaux dans Studio. Leur disponibilité dépend de leur source :

- Les **Tools du projet** doivent être implémentés et enregistrés dans le projet Mastra par un développeur.
- Les **Tools d’intégration** deviennent disponibles après l’enregistrement d’un Provider comme Composio ou Arcade par un développeur. Les collaborateurs peuvent alors parcourir le catalogue du Provider et ajouter des Tools sans que chacun d’eux soit d’abord ajouté dans le code.
- Les **Tools MCP** deviennent disponibles lorsqu’un client MCP est configuré. Un collaborateur autorisé peut créer le client dans Studio, puis choisir parmi les Tools exposés par ses serveurs.

Dans la section **Tools** de l’Agent, les collaborateurs peuvent ajouter les Tools dont il a besoin ou réécrire la description d’un Tool pour cet Agent. Une description plus précise aide l’Agent à comprendre quand utiliser le Tool sans modifier celui-ci.

### Tools du projet

Les développeurs peuvent enregistrer un Tool de projet dans l’instance `Mastra` afin de le rendre accessible dans Editor :

```typescript
import { Mastra } from '@mastra/core'
import { MastraEditor } from '@mastra/editor'
import { searchOrders } from './tools/search-orders'

export const mastra = new Mastra({
  tools: {
    searchOrders,
  },
  agents: {/* agents */},
  editor: new MastraEditor(),
})
```

Le sélecteur de Tools de Studio répertorie le Tool. Un collaborateur peut l’ajouter à un Agent lorsque celui-ci autorise la modification des Tools. La vue Editor de l’Agent répertorie également les Tools associés dans le code.

### Composio

[Composio](https://composio.dev) fournit des Tools pour des services comme GitHub, Slack et Gmail. Enregistrez le Provider avec une clé API Composio afin de rendre son catalogue de Tools accessible dans Editor :

```typescript
import { Mastra } from '@mastra/core'
import { MastraEditor } from '@mastra/editor'
import { ComposioToolProvider } from '@mastra/editor/composio'

export const mastra = new Mastra({
  agents: {/* agents */},
  editor: new MastraEditor({
    toolProviders: {
      composio: new ComposioToolProvider({
        apiKey: process.env.COMPOSIO_API_KEY!,
      }),
    },
  }),
})
```

Les identifiants des Tools Composio ressemblent à `GITHUB_CREATE_ISSUE`. Par défaut, un Tool sélectionné utilise la connexion associée à l’auteur de l’Agent. Consultez la [portée des connexions](https://agent-builder.mastra.ai/tool-providers#connection-scope) pour utiliser plutôt la connexion de chaque appelant.

### Arcade

[Arcade](https://arcade.dev) fournit un autre catalogue de Tools avec authentification intégrée. Enregistrez-le avec une clé API Arcade :

```typescript
import { Mastra } from '@mastra/core'
import { MastraEditor } from '@mastra/editor'
import { ArcadeToolProvider } from '@mastra/editor/arcade'

export const mastra = new Mastra({
  agents: {/* agents */},
  editor: new MastraEditor({
    toolProviders: {
      arcade: new ArcadeToolProvider({
        apiKey: process.env.ARCADE_API_KEY!,
      }),
    },
  }),
})
```

Les identifiants des Tools Arcade utilisent le format `Toolkit.ToolName`, comme `Github.GetRepository`.

### Clients MCP

Les collaborateurs peuvent également créer un client MCP réutilisable dans Studio et ajouter ses Tools à un Agent. Les clients stockés peuvent démarrer un serveur `stdio` local ou se connecter à un serveur HTTP distant. Les filtres de Tools permettent à chaque Agent d’utiliser uniquement ceux dont il a besoin sur ce serveur.

Consultez la [référence des Tools d’Editor](https://mastra.zisheng.pro/fr/reference/editor/tools) pour la configuration MCP, les conditions, le filtrage et l’ordre de résolution. Consultez [`ToolProvider`](https://mastra.zisheng.pro/fr/reference/editor/tool-provider) pour les options des Providers.

## Déterminer ce que les collaborateurs peuvent modifier

Par défaut, les collaborateurs peuvent modifier les instructions d’un Agent et gérer ses Tools, y compris leurs descriptions. L’`id`, le `name` et le `model` de l’Agent proviennent toujours du code.

Utilisez le champ `editor` de l’Agent pour limiter les éléments modifiables :

```typescript
import { Agent } from '@mastra/core/agent'

export const supportAgent = new Agent({
  id: 'support-agent',
  name: 'Support agent',
  instructions: 'Help customers with Acme products.',
  model: 'openai/gpt-5.6-sol',
  editor: {
    instructions: true,
    tools: {
      description: true,
    },
  },
})
```

Cet Agent permet aux collaborateurs de modifier ses instructions et d’améliorer la description des Tools qui lui sont déjà associés. Ils ne peuvent ni ajouter ni supprimer de Tools.

| Valeur de `editor`                 | Éléments modifiables par les collaborateurs      |
| ---------------------------------- | ------------------------------------------------ |
| Omise                              | Instructions, Tools et descriptions des Tools    |
| `false`                            | Aucun élément                                    |
| `{ instructions: true }`           | Instructions                                     |
| `{ tools: true }`                  | Tools et descriptions des Tools                  |
| `{ tools: { description: true } }` | Descriptions des Tools déjà ajoutés dans le code |

Studio affiche tous les autres éléments en lecture seule. Consultez les [remplacements d’Editor](https://mastra.zisheng.pro/fr/reference/agents/agent) pour obtenir la configuration complète.

## Choisir où stocker les modifications

Editor peut enregistrer les modifications dans la base de données configurée ou sous forme de fichiers dans le dépôt.

### Stockage en base de données

La base de données est l’option par défaut. Editor utilise le stockage configuré dans l’instance `Mastra`, ce qui permet à l’application et à Editor de partager le même backend.

Pour utiliser un backend distinct pour les données d’Editor, définissez l’option `editor` de [`MastraCompositeStore`](https://mastra.zisheng.pro/fr/reference/storage/composite). Les domaines de stockage sans route explicite continuent d’utiliser son stockage `default`.

L’exemple suivant conserve les données de l’application et d’Editor dans des fichiers LibSQL distincts :

```typescript
import { Mastra } from '@mastra/core'
import { MastraCompositeStore } from '@mastra/core/storage'
import { MastraEditor } from '@mastra/editor'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  agents: {/* existing agents */},
  storage: new MastraCompositeStore({
    id: 'mastra-storage',
    default: new LibSQLStore({
      id: 'app-storage',
      url: 'file:./mastra.db',
    }),
    editor: new LibSQLStore({
      id: 'editor-storage',
      url: 'file:./editor.db',
    }),
  }),
  editor: new MastraEditor(),
})
```

### Fichiers du dépôt

Utilisez la source de code afin de conserver les remplacements avec le code de l’application. Les développeurs peuvent examiner les fichiers dans des pull requests et les déployer avec l’application :

```typescript
import { Mastra } from '@mastra/core'
import { MastraEditor } from '@mastra/editor'

export const mastra = new Mastra({
  agents: {/* existing agents */},
  editor: new MastraEditor({
    source: 'code',
    codePath: './mastra/editor',
  }),
})
```

Dans ce mode, chaque Agent modifié possède un fichier JSON de remplacement. Editor ne génère pas de TypeScript et ne modifie pas le fichier dans lequel l’Agent a été créé. Par défaut, un Agent dont l’identifiant est `support-agent` reçoit le fichier suivant :

```text
mastra/editor/agents/support-agent.json
```

Le fichier contient uniquement les parties gérées par Editor. Par exemple :

```json
{
  "instructions": "Help customers with Acme products and answer in their language.",
  "tools": {
    "searchOrders": {
      "description": "Look up an order by its number"
    }
  }
}
```

Le modèle, le nom et les autres champs de l’Agent contrôlés par le code restent dans son fichier TypeScript. Mastra lit le JSON et applique ces valeurs lors de l’exécution de l’Agent.

Lorsqu’un collaborateur enregistre dans Studio, il peut écrire le fichier dans le système de fichiers local ou le télécharger. Avec une intégration de gestion du code source, Studio peut plutôt ouvrir une pull request. Git fournit alors la révision et l’historique des versions.

Consultez [`MastraEditor`](https://mastra.zisheng.pro/fr/reference/editor/mastra-editor) pour les emplacements de fichiers et les options de source.

## Gestion des versions

Les Agents et blocs de prompts stockés en base de données utilisent des versions brouillon et publiées. L’enregistrement crée un brouillon tandis que l’Agent en production continue d’utiliser la version publiée. La publication met le brouillon en production. Restaurer une ancienne version crée un brouillon que les collaborateurs peuvent tester avant de le publier.

Les remplacements d’Agents stockés dans le code utilisent des fichiers JSON et l’historique Git.

### Sélectionner une version

Une application peut choisir une version stockée pour chaque requête en transmettant un état (`published` ou `draft`) ou un identifiant de version précis :

```typescript
const publishedAgent = await mastra.getAgentById('support-agent', {
  status: 'published',
})

const draftAgent = await mastra.getAgentById('support-agent', {
  status: 'draft',
})

const versionedAgent = await mastra.getAgentById('support-agent', {
  versionId: 'abc-123',
})
```

La sélection de version permet de :

- Comparer deux versions dans un test A/B.
- Donner accès à un brouillon à un petit groupe avant de le publier pour tous.
- Maintenir la production sur la version publiée tandis que la préproduction utilise le dernier brouillon.
- Épingler un client à une version précise.

Les mêmes contrôles de version fonctionnent lorsqu’un superviseur appelle des sous-Agents. Les développeurs peuvent tester le brouillon d’un sous-Agent sans modifier le reste du système.

Consultez la [référence de la gestion des versions d’Editor](https://mastra.zisheng.pro/fr/reference/editor/versioning) pour la sélection des versions, le comportement des sous-Agents, les points de terminaison REST et les méthodes du SDK.

## Accès programmatique

Tout ce qui est accessible dans Studio l’est également de manière programmatique au moyen de [`mastra.getEditor()`](https://mastra.zisheng.pro/fr/reference/core/getEditor), de l’API REST ou du SDK client. Utilisez ces interfaces pour automatiser des mises à jour en masse ou initialiser depuis le code des configurations stockées. Elles peuvent également alimenter des automatisations qui ajustent les Agents en fonction des [résultats d’évaluation](https://mastra.zisheng.pro/fr/docs/datasets/running-experiments).

Appelez `mastra.getEditor()` lorsque le code de l’application a accès à l’instance Mastra :

```typescript
import { mastra } from '../mastra'

const editor = mastra.getEditor()!

await editor.agent.update({
  id: 'support-agent',
  instructions: 'Help customers with Acme products. Reply in their language.',
})
```

La méthode directe `editor.agent.update()` active immédiatement la nouvelle version. Pour créer un brouillon sans modifier l’Agent en production, utilisez plutôt l’API REST des Agents stockés ou le SDK client :

```bash
curl -X PATCH http://localhost:4111/api/stored/agents/support-agent \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Help customers with Acme products. Reply in their language."
  }'
```

Le préfixe par défaut du serveur est `/api`. Les développeurs peuvent définir un préfixe personnalisé dans la configuration du serveur.

Consultez les [espaces de noms de `MastraEditor`](https://mastra.zisheng.pro/fr/reference/editor/mastra-editor) et l’[API Agents du SDK client](https://mastra.zisheng.pro/fr/reference/client-js/agents) pour connaître les opérations disponibles.

## Étapes suivantes

- [Référence de MastraEditor](https://mastra.zisheng.pro/fr/reference/editor/mastra-editor)
- [Référence des blocs de prompts](https://mastra.zisheng.pro/fr/reference/editor/prompt-blocks)
- [Référence des Tools d’Editor](https://mastra.zisheng.pro/fr/reference/editor/tools)
- [Référence de la gestion des versions d’Editor](https://mastra.zisheng.pro/fr/reference/editor/versioning)