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

# Gestion des versions

Editor gère les versions des Agents stockés et des blocs de prompt. Les ressources enregistrées en base de données utilisent des opérations de brouillon et de publication. Les surcharges d'Agents basées sur le code utilisent des fichiers déterministes et l'historique Git.

Consultez la [gestion des versions dans Editor](https://mastra.zisheng.pro/fr/docs/editor/overview) pour découvrir les modèles de publication et d'expérimentation.

## Cycle de vie en base de données

L'enregistrement de la ressource conserve un `activeVersionId`. Les snapshots individuels ne stockent aucun état de cycle de vie.

| Terme            | Signification                                                                                        |
| ---------------- | ---------------------------------------------------------------------------------------------------- |
| Dernière version | Le snapshot de configuration créé le plus récemment                                                  |
| Publiée          | Le snapshot sélectionné par `activeVersionId`                                                        |
| Brouillon        | Le dernier snapshot lorsqu'il diffère de `activeVersionId`, ou lorsqu'aucune version active n'existe |
| Historique       | Tout autre snapshot conservé                                                                         |

L'enregistrement de champs de snapshot modifiés crée une nouvelle version la plus récente. L'enregistrement de champs identiques ou la seule modification des métadonnées ne crée aucune version.

Lorsqu'une version active existe, la création d'un brouillon ne modifie pas la version qui traite les requêtes publiées. La publication met à jour `activeVersionId`. La restauration d'une version historique copie sa configuration dans un nouveau brouillon inactif.

Les méthodes directes du namespace et les API REST présentent une différence importante. `editor.prompt.update()` crée un brouillon inactif. `editor.agent.update()` crée une version et l'assigne immédiatement à `activeVersionId`. La route REST `PATCH` des Agents stockés crée un brouillon inactif, sauf si `autoPublish` est activé.

Lorsqu'une ressource stockée générique ne possède aucune version active, la résolution de la version publiée peut se rabattre sur le dernier snapshot. Pour la surcharge d'un Agent défini dans le code, une requête avec `status: 'published'` sans surcharge active renvoie l'Agent d'origine défini dans le code.

## Source basée sur le code

Avec `source: 'code'`, les surcharges actives des Agents sont sérialisées sous forme de JSON déterministe dans `<codePath>/agents/<encodedAgentId>.json`. La valeur par défaut de `codePath` est `./mastra/editor`.

L'Agent initial est publié afin de créer le fichier. Par défaut, les mises à jour ultérieures effectuées par le serveur créent un brouillon et écrivent le fichier lorsque cette version devient active. Dans Studio, les versions Git sont en lecture seule et utilisent le message de commit comme message de modification. L'analyse de l'historique lit par défaut jusqu'à 50 commits récents et ignore les commits consécutifs dont le snapshot JSON analysé est identique.

Consultez [`MastraEditor`](https://mastra.zisheng.pro/fr/reference/editor/mastra-editor) pour connaître les options de source.

## Sélectionner une version d'Agent

L'appel de [`mastra.getAgentById()`](https://mastra.zisheng.pro/fr/reference/core/getAgentById) sans sélecteur renvoie l'Agent enregistré défini dans le code. Transmettez `status` ou `versionId` pour appliquer une surcharge stockée. Consultez [Sélectionner une version](https://mastra.zisheng.pro/fr/docs/editor/overview) pour obtenir un exemple TypeScript.

Avec le préfixe de serveur par défaut, transmettez les sélecteurs sous forme de paramètres de requête sous `/api` :

```bash
# Published version
curl http://localhost:4111/api/agents/support-agent

# Latest draft
curl http://localhost:4111/api/agents/support-agent?status=draft

# Exact version
curl http://localhost:4111/api/agents/support-agent?versionId=abc-123
```

Consultez la [référence des Agents du Client SDK](https://mastra.zisheng.pro/fr/reference/client-js/agents) pour les sélecteurs du Client SDK et du React SDK.

## Gestion des versions des sous-agents

Les surcharges de version se propagent dans le contexte de requête par l'intermédiaire de la [délégation de l'Agent superviseur](https://mastra.zisheng.pro/fr/docs/capabilities/subagents). Définissez les sélecteurs à trois niveaux :

1. Instance `Mastra`, propriété `versions` : valeurs par défaut de chaque invocation
2. `versions` du corps de la requête serveur : valeurs propres à la requête ajoutées au contexte
3. Appel direct à `generate()` ou `stream()`, option `versions` : valeurs propres à l'invocation

Les entrées sont fusionnées par ID d'Agent. Pour un même ID, l'ordre de priorité est le suivant : **invocation directe > corps de la requête ou contexte de requête existant > valeur par défaut de l'instance Mastra**.

Définissez les valeurs par défaut sur l'instance Mastra :

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

export const mastra = new Mastra({
  agents: { supervisor, researchAgent, writerAgent },
  editor: new MastraEditor(),
  versions: {
    agents: {
      'research-agent': { status: 'published' },
      'writer-agent': { versionId: 'abc-123' },
    },
  },
})
```

Surchargez un sous-agent pour une invocation directe :

```typescript
const result = await supervisor.generate('Research and write about AI safety', {
  versions: {
    agents: {
      'research-agent': { status: 'draft' },
    },
  },
})
```

Vous pouvez également transmettre les sélecteurs dans le corps de la requête serveur :

```bash
curl -X POST http://localhost:4111/api/agents/supervisor/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "Research AI safety" }],
    "versions": {
      "agents": {
        "research-agent": { "status": "draft" }
      }
    }
  }'
```

Si Editor n'est pas configuré ou qu'une version ne peut pas être résolue, Mastra consigne un avertissement et utilise le sous-agent défini dans le code.

## API REST des Agents stockés

Le préfixe par défaut du serveur Mastra est `/api`. Un préfixe de serveur personnalisé modifie les chemins ci-dessous.

| Méthode  | Chemin                                         | Description                                                                             |
| -------- | ---------------------------------------------- | --------------------------------------------------------------------------------------- |
| `GET`    | `/api/stored/agents`                           | Répertorier les Agents stockés                                                          |
| `POST`   | `/api/stored/agents`                           | Créer un Agent stocké                                                                   |
| `GET`    | `/api/stored/agents/:storedAgentId`            | Récupérer un Agent stocké                                                               |
| `PATCH`  | `/api/stored/agents/:storedAgentId`            | Mettre à jour un Agent stocké                                                           |
| `DELETE` | `/api/stored/agents/:storedAgentId`            | Supprimer un Agent stocké                                                               |
| `GET`    | `/api/stored/agents/:storedAgentId/dependents` | Répertorier les dépendants lisibles et compter les références masquées entre Workspaces |
| `POST`   | `/api/stored/agents/:storedAgentId/export`     | Exporter en JSON déterministe les champs de surcharge autorisés                         |

La réponse des dépendants répertorie les Agents lisibles par l'appelant selon leur `id` et leur `name`. Son champ `hiddenCount` compte les références entre Workspaces que l'appelant ne peut pas lire, mais uniquement lorsque l'Agent cible est public.

Les routes de gestion des versions se trouvent sous `/api/stored/agents/:storedAgentId/versions`. Consultez la [gestion des versions](https://mastra.zisheng.pro/fr/reference/client-js/agents) pour connaître les opérations et les méthodes du Client SDK.

Le Client SDK expose `listStoredAgents()`, `createStoredAgent()` et `getStoredAgent()`. La ressource renvoyée par `getStoredAgent(id)` comprend des méthodes de mise à jour, de suppression, de gestion des dépendants, d'export et de gestion des versions.