Guide de migration

English version: ../../en/guides/migration.md

Ce guide explique comment l'API et les contrats restent compatibles, et comment mettre à jour le SDK, la CLI et vos manifestes vers une nouvelle version sans casser un agent déployé. Qui : développeurs et responsables de version. Durée : environ 15 minutes par projet.

Compatibilité

L'API est versionnée sous /v1 ; services/control-plane/src/eai/api_openapi.py refuse de régénérer docs/api/openapi-v1.json sur un changement cassant, donc une montée de version mineure du SDK reste compatible. Les contrats portent schema_version.

Quoi	Règle	Où c'est vérifié
Routes et champs de l'API	ajoutés, jamais retirés ni retypés sous /v1	services/control-plane/src/eai/api_openapi.py (--check en CI)
Surface des requêtes	chaque route a sa description de requête publiée	docs/api/control-plane-v1.requests.json, services/control-plane/tests/test_api_surface.py
Contrats JSON Schema	chaque document porte schema_version ; le SDK valide selon les contrats qu'il embarque	contracts/v1, enterprise-ai test sdk-conformance
Enveloppe d'erreur	code, message, message_i18n, details, request_id gardent leur sens	erreurs typées des SDK

Mettre à jour

Mettre à jour le SDK, puis revalider les manifestes et lancer les tests de conformité avant de redéployer.

pip install -U enterprise-ai
enterprise-ai doctor
enterprise-ai validate -f agent.yaml
enterprise-ai test sdk-conformance

Procédure

1. Lire les notes de version. Elles listent les nouveautés, changements, corrections et problèmes connus de la version : vous savez quels manifestes revoir.

   Ouvrez les notes de version de la version cible.

   Résultat attendu : vous avez la liste des contrats et des routes modifiés que vos projets utilisent.

   En cas d'échec : si un changement n'est pas listé, comparez le schéma publié docs/api/openapi-v1.json des deux versions.

2. Mettre à jour le SDK et la CLI. La CLI est livrée avec le SDK Python : une seule mise à jour couvre les deux.

   pip install -U enterprise-ai

   Résultat attendu : pip show enterprise-ai affiche la nouvelle version.

   En cas d'échec : vérifiez l'index de paquets ou le miroir que lit votre pip.

3. Vérifier les versions face au Control Plane. enterprise-ai doctor vérifie que le serveur annonce la version d'API v1 (GET /v1/meta) et connaît chaque contrat embarqué par le SDK (GET /v1/contracts).

   enterprise-ai doctor

   Résultat attendu : le contrôle versions est à PASS.

   En cas d'échec : FAIL signale que le serveur n'annonce pas la version d'API v1 ; WARN liste des contrats inconnus du serveur. Mettez à jour le côté en retard.

4. Revalider chaque manifeste. Un contrat plus récent peut ajouter un champ obligatoire ou une règle plus stricte.

   enterprise-ai validate -f agent.yaml

   Résultat attendu : le manifeste est valide.

   En cas d'échec : corrigez chaque champ signalé ; à distance, le même contrôle est POST /v1/contracts/{name}/validate, qui répond "valid": false avec la liste des errors.

5. Lancer les tests de conformité et du projet. Ils prouvent que le SDK et le serveur s'accordent et que l'agent se comporte comme avant.

   enterprise-ai test sdk-conformance
   enterprise-ai test authz
   enterprise-ai test security --threshold 0

   Résultat attendu : code de sortie 0 pour chaque commande.

   En cas d'échec : code de sortie 1 ; voir le Guide de tests.

6. Déployer en dev, puis promouvoir. Un déploiement passe par la porte qualité ; une promotion vers prod demande son approbation.

   enterprise-ai deploy agent -f agent.yaml --env dev

   Résultat attendu : la nouvelle version apparaît dans Agents > Registre (GET /v1/agents/{agent_id}/versions).

   En cas d'échec : 409 gate_failed liste les contrôles en échec dans details.failures.

Notes par SDK

Les tableaux « Endpoints and fields aligned with the backend » des guides TypeScript et Go listent les champs et routes alignés sur l'API v1 et les contrats 1.1.

Dépannage

Symptôme	Cause	Correction
enterprise-ai doctor : versions à FAIL	le serveur n'annonce pas la version d'API v1	mettez à jour le SDK ou le Control Plane pour les aligner
enterprise-ai doctor : versions à WARN	le serveur ne connaît pas un contrat du SDK	mettez à jour le Control Plane, ou gardez le SDK précédent
enterprise-ai test sdk-conformance sort en code 1	écart de contrat	alignez la version du SDK sur le serveur
422 invalid_manifest à l'application d'un manifeste	nouveau champ obligatoire ou règle plus stricte	corrigez le manifeste, revalidez
409 gate_failed au déploiement	la nouvelle version échoue à une cible d'évaluation ou de red team	corrigez, relancez les suites

Étapes suivantes

• Guide de tests
• Référence API
• Guides SDK : Python, TypeScript, Go, Java