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 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 pour connaître les options de source.

Sélectionner une version d'Agent

L'appel de mastra.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 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 :

Version selection through the API

# 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 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. 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 :

src/mastra/index.ts

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 :

src/routes/experiment.ts

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 :

Per-request sub-agent versions

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