Agent versioning pour les agents IA : comment déployer prompt, tools et policy en sécurité

L’idée en 30 secondes

Agent versioning est un contrôle runtime qui fixe exactement quelle version d’agent chaque run utilise : prompt, tools, policy et modèle.

Quand c’est nécessaire : quand un agent est mis à jour régulièrement et que la production exige des déploiements sûrs sans perdre la reproductibilité.

Le problème

Sans versioning, les changements de prompt, tools et policy se mélangent dans un seul "état courant". En démo, cela se voit peu. En production, on ne comprend plus pourquoi un run a réussi et un autre non.

Conséquences typiques :

• impossible de reproduire précisément un incident
• difficile d’identifier le changement qui a cassé le comportement
• rollback devient une opération manuelle et risquée

Et chaque minute sans version claire augmente le temps d’investigation d’incident.

Analogie : c’est comme un déploiement sans numéro de version. Tant que tout marche, le problème est invisible. Quand ça casse, on ne sait pas vers quoi revenir.

La solution

La solution est de stocker l’agent comme package versionné (version manifest) et de démarrer les runs uniquement avec un version_id pin. Chaque release passe des vérifications de compatibilité des contrats et un rollout gate avant de recevoir du trafic.

Version policy layer renvoie une décision technique : allow ou stop avec raison explicite :

• contract_mismatch
• gate_failed
• rollback_required

C’est une couche système séparée, pas une partie du prompt ni de la logique du modèle.

Agent versioning ≠ rollback

Ce sont des rôles différents dans le système :

• Versioning contrôle les changements avant et pendant le rollout.
• Rollback ramène une version stable quand la nouvelle a déjà introduit une régression.

L’un sans l’autre ne suffit pas :

• sans versioning, rollback ciblé est difficile
• sans rollback, même un bon versioning ne protège pas d’un incident production

Exemple :

• versioning : support-agent@2.4.0 va en canary 5%
• rollback : retour à support-agent@2.3.3 si le taux d’erreur augmente

Composants du contrôle de versioning

Ces composants travaillent ensemble à chaque démarrage de run.

Exemple d’alerte :

Slack: 🛑 Agent support@2.4.0 blocked: gate_failed on canary stage (error_rate > threshold).

À quoi ça ressemble dans l’architecture

Version policy layer se place entre runtime et le démarrage d’une nouvelle version d’agent, et bloque le démarrage avant le début du run. Chaque décision (allow ou stop) est écrite dans l’audit log.

Chaque démarrage de run passe par ce flow avant exécution : runtime ne démarre pas une nouvelle version directement, il demande d’abord une décision à la policy layer.

Résumé du flow :

• Runtime prépare le démarrage du run
• Policy vérifie version_manifest, tool_contracts, rollout_stage, policy_version
• allow -> la agent_version pin démarre
• stop -> release bloqué, la version stable active reste en place
• les deux décisions sont écrites dans l’audit log

Exemple

L’équipe release support-agent@2.4.0 avec un nouvel adaptateur tool refund.create. Le contract check détecte une incompatibilité de schéma.

Résultat :

• policy renvoie stop (reason=contract_mismatch)
• canary ne démarre pas
• support-agent@2.3.3 continue de tourner

Versioning arrête le release risqué avant l’incident, pas après.

En code, ça ressemble à ça

Le schéma simplifié ci-dessus montre le flow principal. Point critique : runtime doit démarrer les runs uniquement avec un version_id pin, pas récupérer "latest" pendant l’exécution.

Exemple de config versioning :

agent_release:
  stable_version: support-agent@2.3.3
  candidate_version: support-agent@2.4.0
  canary_percent: 5
  rollback_on:
    error_rate_p95: 0.05
    tool_failure_p95: 0.03

release_cfg = load_release_config("support-agent")
candidate = registry.get(release_cfg.candidate_version)
decision = versioning.check(candidate, runtime_context)

if decision.outcome == "stop":
    audit.log(
        run_id,
        decision=decision.outcome,
        reason=decision.reason,
        version_id=candidate.version_id,
        rollout_stage=decision.rollout_stage,
    )
    alerts.notify_if_needed(candidate.version_id, decision.reason)
    return stop(decision.reason)

selected = versioning.select(candidate, stable=release_cfg.stable_version)
run = runtime.start(
    version_id=selected.version_id,
    prompt_hash=selected.prompt_hash,
    policy_version=selected.policy_version,
)
# Decision.allow — helper conditionnel pour garder un modèle unique outcome/reason.
allow_decision = Decision.allow(reason=None)

audit.log(
    run.id,
    decision=allow_decision.outcome,
    reason=allow_decision.reason,
    version_id=selected.version_id,
    rollout_stage=selected.rollout_stage,
)

return run

À quoi ça ressemble pendant l’exécution

Scénario 1 : blocage à cause d’un contract mismatch

1. Runtime prépare le démarrage de support-agent@2.4.0.
2. Policy vérifie les tool contracts.
3. Décision : stop (reason=contract_mismatch).
4. La nouvelle version ne démarre pas.
5. L’événement est écrit dans l’audit log.

Scénario 2 : canary rollout

1. Policy autorise le candidate avec canary_percent=5.
2. Une partie des runs passe sur 2.4.0, le reste reste sur stable.
3. Les métriques sont suivies par version_id.
4. Si les seuils ne sont pas dépassés, la stage augmente.
5. La version passe en rollout plus large.

Scénario 3 : rollback required

1. Après le rollout, tool_failure_rate augmente.
2. Policy renvoie stop (reason=rollback_required).
3. Le trafic revient à la version stable.
4. Les runs avec la nouvelle version ne démarrent plus.
5. L’équipe analyse l’incident via version_id et audit trail.

Erreurs typiques

• démarrer les runs depuis "latest" au lieu d’un version_id pin
• versionner seulement le prompt et ignorer les contracts tools/policy
• faire un full rollout sans canary gate
• ne pas logger version_id et rollout_stage dans l’audit
• mélanger rollback et nouveau release dans une seule étape sans stable fallback
• ne pas définir de seuils explicites qui déclenchent rollback

Résultat : les déploiements semblent maîtrisés, mais sous charge deviennent imprévisibles.

Auto-vérification

Vérification rapide d’agent versioning avant lancement en production :

FAQ

Q : Pourquoi ne pas simplement mettre à jour la version "courante" de l’agent ?
A : Parce que sans version_id pin, tu perds la reproductibilité des runs et tu ne peux pas localiser précisément les régressions.

Q : Qu’est-ce qu’il faut versionner exactement : seulement le prompt ?
A : Non. Minimum : prompt, tool contracts, policy/config et compatibilité runtime. Sinon la version est incomplète.

Q : Canary est-il obligatoire pour chaque changement ?
A : Pour les changements high-risk, oui. Pour low-risk, on peut raccourcir les étapes, mais avec métriques explicites et seuils de stop.

Q : Quand lancer rollback ?
A : Quand les seuils convenus sont dépassés (error/tool failure/latency/cost). Cela doit être une décision policy, pas une improvisation manuelle.

Q : Versioning remplace rollback ?
A : Non. Versioning évite le chaos des déploiements, rollback reste le mécanisme d’urgence de retour au stable.

Où Agent Versioning se place dans le système

Agent versioning est une des couches d’Agent Governance. Avec RBAC, limites, budgets, approval et audit, il forme un système unifié de changements contrôlés en production.

Pages liées

Suite du sujet :

• Vue d’ensemble Agent Governance — modèle global de contrôle des agents en production.
• Stratégies de rollback — comment revenir en sécurité vers une version stable.
• Access Control (RBAC) — comment limiter qui peut exécuter quoi.
• Budget Controls — comment garder la dépense sous contrôle pendant rollout.
• Audit logs pour agents — comment reconstruire la chaîne de décisions par version_id.