Versioning des agents

Expérimentez en toute sécurité les configurations d’agent grâce aux branches, aux versions et au déploiement du trafic

Le versioning des agents vous permet d’expérimenter différentes configurations de votre agent sans risquer votre environnement de production. Créez des branches isolées, testez les modifications et déployez progressivement les mises à jour à l’aide du déploiement par pourcentage de trafic.

Vous souhaitez réaliser des tests A/B ? Consultez Expériences pour découvrir le workflow recommandé afin de tester les modifications apportées aux agents sur du trafic réel.

Vue d’ensemble

Le système de versioning offre :

Des instantanés immuables de la configuration de votre agent à tout moment
Des branches isolées pour tester les modifications avant leur mise en production
La répartition du trafic pour déployer progressivement les modifications auprès d’un pourcentage d’utilisateurs
La fusion pour intégrer les modifications d’une branche dans une autre
Le rebasage pour intégrer dans une branche les dernières modifications de la branche principale

Une fois le versioning activé pour un agent, il ne peut plus être désactivé. Tenez-en compte avant d’activer le versioning sur des agents existants.

Concepts clés

Versions

Une version est un instantané immuable de la configuration d’un agent à un moment précis. Chaque version possède un ID unique (format : agtvrsn_xxxx) et contient :

conversation_config - Prompt système, paramètres du LLM, configuration vocale, outils, base de connaissances
platform_settings - Sous-ensemble versionné incluant les paramètres d’évaluation, de widget, de collecte de données et de sécurité
workflow - Définition complète du workflow avec nœuds et arêtes

Les versions sont créées automatiquement lorsque vous enregistrez des modifications sur un agent versionné. Une fois créée, une version ne peut pas être modifiée.

Branches

Les branches sont des lignes de développement nommées, semblables aux branches git. Elles vous permettent de travailler sur des modifications de manière isolée avant de les fusionner dans la branche principale.

Chaque agent versionné possède une branche Main qui ne peut être ni supprimée ni archivée
Des branches supplémentaires peuvent être créées à partir de n’importe quelle version de toute branche existante, et pas uniquement de la branche principale
Les branches peuvent être fusionnées dans toute autre branche, et les branches autres que la branche principale peuvent être rebasées sur celle-ci afin d’intégrer ses dernières modifications
Chaque branche possède : un ID (agtbrch_xxxx), un nom, une description et une liste de versions
Les noms de branche peuvent contenir : des lettres, des chiffres et () [] {} - / . (140 caractères maximum)

Déploiement du trafic

Le trafic peut être réparti entre plusieurs branches par pourcentage, ce qui permet des déploiements progressifs et des tests A/B.

Les pourcentages doivent toujours totaliser exactement 100 %
Le routage du trafic est déterministe en fonction de l’ID de conversation (un même utilisateur est systématiquement dirigé vers la même branche)
Seules les branches non archivées avec 0 % de trafic peuvent être archivées

Brouillons

Les modifications non enregistrées sont stockées sous forme de brouillons, ce qui vous permet de travailler sur des modifications sans créer immédiatement une nouvelle version.

Les brouillons sont propres à chaque utilisateur et à chaque branche (chaque membre de l’équipe dispose de son propre brouillon)
Les brouillons sont automatiquement supprimés lorsqu’une nouvelle version est validée
Les brouillons sont également supprimés lors de la fusion dans une branche

Activer le versioning

Le versioning est facultatif et doit être activé explicitement. Vous pouvez l’activer lors de la création d’un nouvel agent ou sur un agent existant.

Une fois activé, le versioning ne peut plus être désactivé. Cette modification est permanente pour votre agent.

Activer lors de la création d’un agent

Activer depuis le Dashboard

Activer via l’API

Ouvrez votre agent dans le Dashboard, accédez à Settings, puis activez le versioning. Une fois activé, l’onglet Versioning vous permet de gérer les branches, les brouillons, les versions et le déploiement du trafic.

Activer sur un agent existant

Activer depuis le Dashboard

Activer via l’API

Ouvrez votre agent dans le Dashboard, accédez à Settings, puis activez le versioning.

L’activation du versioning crée la branche initiale « Main » avec une première version contenant la configuration actuelle de l’agent.

Travailler avec les branches

Créer une branche

Les branches peuvent être créées à partir de n’importe quelle version de toute branche, et pas uniquement de la branche principale. Vous pouvez éventuellement inclure des modifications de configuration qui seront appliquées à la version initiale de la nouvelle branche.

branch = client.conversational_ai.agents.branches.create(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    parent_version_id="agtvrsn_xxxx",
    name="experiment-v2",
    description="Testing new prompt and voice settings"
)
print(f"Created branch: {branch.created_branch_id}")
print(f"Initial version: {branch.created_version_id}")

Lister les branches

branches = client.conversational_ai.agents.branches.list(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
)
for branch in branches.branches:
print(f"{branch.name}: {branch.id}")

Obtenir les détails d’une branche

branch = client.conversational_ai.agents.branches.get(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx"
)
print(f"Branch: {branch.name}")
print(f"Versions: {len(branch.versions)}")

Valider les modifications

Lorsque vous mettez à jour un agent avec le versioning activé, indiquez branch_id pour créer une nouvelle version dans cette branche.

Mettre à jour depuis le Dashboard

Mettre à jour via la CLI

Mettre à jour via l’API

Ouvrez l’onglet Versioning de votre agent, basculez vers la branche cible, modifiez la configuration et enregistrez pour créer une nouvelle version.

Une nouvelle version est automatiquement créée dans la branche indiquée, et tout brouillon existant pour cet utilisateur dans cette branche est supprimé.

Déployer le trafic

Utilisez le point de terminaison deployments pour répartir le trafic entre les branches. Cela permet des déploiements progressifs et des tests A/B.

deployment = client.conversational_ai.agents.deployments.create(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    deployments=[
        {"branch_id": "agtbrch_main", "percentage": 90},
        {"branch_id": "agtbrch_xxxx", "percentage": 10}
    ]
)

La somme de tous les pourcentages doit être exactement égale à 100 %. Le déploiement échouera dans le cas contraire.

Le routage du trafic est déterministe en fonction de l’ID de conversation, ce qui garantit qu’un même utilisateur accède systématiquement à la même branche d’une session à l’autre.

Fusionner des branches

Lorsque les modifications d’une branche vous conviennent, fusionnez-les dans une autre branche. Toute branche non archivée peut être fusionnée dans toute autre branche non archivée, et pas seulement dans la branche principale.

Pour faire examiner les modifications d’une branche avant leur fusion, ou pour accéder à une branche pour laquelle vous ne disposez pas d’un accès en écriture, ouvrez plutôt une proposition de fusion que d’effectuer la fusion directement.

merge = client.conversational_ai.agents.branches.merge(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    source_branch_id="agtbrch_xxxx",
    target_branch_id="agtbrch_main",
    archive_source_branch=True,  # Default: true
    force=False  # Default: false
)

La fusion :

Crée une nouvelle version dans la branche cible avec la configuration de la branche source
Archive éventuellement la branche source (comportement par défaut)
Transfère automatiquement le trafic de la branche source vers la branche cible

La fusion échoue avec no_new_changes_to_merge si la branche source a été créée à partir de la branche cible (et ne comporte aucune nouvelle validation au-delà de celle-ci), et avec branch_already_merged si elle a déjà été fusionnée dans cette cible.

Résoudre les conflits de fusion

Si un paramètre a été modifié à la fois dans la branche source et dans la branche cible depuis leur divergence, la valeur de la branche mise à jour le plus récemment est conservée par défaut. Définissez force=True pour toujours utiliser la valeur de la branche source, quels que soient les horodatages.

Prévisualisez le résultat d’une fusion, y compris les champs qui seraient remplacés, avant de la valider :

preview = client.conversational_ai.agents.branches.preview_merge(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    source_branch_id="agtbrch_xxxx",
    target_branch_id="agtbrch_main",
    force=False
)
print(preview.overridden_fields)
print(preview.conflicts)

Rebaser des branches sur la branche principale

Le rebasage intègre les dernières modifications de la branche principale dans une autre branche, à l’image d’un rebase git. Cela permet de maintenir à jour une branche de longue durée par rapport à la branche principale, sans encore y fusionner les propres modifications de cette branche.

client.conversational_ai.agents.branches.rebase(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx"
)

Le rebasage :

Crée une nouvelle version dans la branche qui intègre les dernières modifications de la branche principale
Préserve les propres modifications de la branche : si un paramètre a été modifié à la fois dans la branche et dans la branche principale, la valeur de la branche est toujours conservée
Échoue avec branch_already_up_to_date si la branche inclut déjà toutes les modifications de la branche principale

Seules les branches autres que la branche principale peuvent être rebasées, et uniquement sur la branche principale. Rebaser la branche principale elle-même renvoie une erreur cannot_rebase_main.

Prévisualisez le résultat d’un rebasage avant de le valider :

preview = client.conversational_ai.agents.branches.preview_rebase(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx"
)
print(preview.overridden_fields)

Archiver des branches

Archivez les branches dont vous n’avez plus besoin. Cela permet de garder votre liste de branches organisée.

client.conversational_ai.agents.branches.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx",
    archived=True
)

Vous ne pouvez pas archiver une branche à laquelle du trafic est attribué. Supprimez tout le trafic avant de l’archiver.

Les branches archivées peuvent être désarchivées en définissant archived=False.

Dupliquer un agent versionné

Dupliquer un agent crée un nouvel agent contenant une copie de chaque branche non archivée de l’agent source, et pas uniquement de la branche principale.

duplicate = client.conversational_ai.agents.duplicate(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    name="Copy of my agent"
)
print(duplicate.agent_id)

Dans l’agent dupliqué :

La branche principale est créée à partir de la dernière version de la branche principale de l’agent source
Chaque autre branche non archivée est recréée avec le même nom et la même description, à partir de la dernière version de cette branche
Chaque branche commence avec une seule version, car l’historique des versions n’est pas copié
Les branches archivées et les brouillons ne sont pas copiés
Les déploiements de trafic ne sont pas copiés : tout le trafic est donc dirigé vers la branche principale jusqu’à ce que vous déployiez du trafic vers d’autres branches

Les ID de branche et de version du duplicata sont nouveaux ; mettez donc à jour toutes les références aux ID de l’agent source.

Récupérer des versions spécifiques

Vous pouvez récupérer un agent dans une version spécifique ou à l’extrémité d’une branche.

Obtenir un agent dans une version spécifique

agent = client.conversational_ai.agents.get(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    version_id="agtvrsn_xxxx"
)

Obtenir un agent à l’extrémité d’une branche

agent = client.conversational_ai.agents.get(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx"
)

Inclure les modifications du brouillon

agent = client.conversational_ai.agents.get(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx",
    include_draft=True
)

Référence des paramètres

Paramètres versionnés

Ces paramètres peuvent différer selon les versions et les branches :

Catégorie	Paramètres
Configuration de conversation	Prompt système, personnalité de l’agent, sélection et paramètres du LLM, paramètres vocaux (modèle TTS, ID vocal), configuration des outils, base de connaissances, premier message, paramètres de langue, détection de tour de parole, paramètres d’interruption
Paramètres de plateforme versionnés	`evaluation` - critères d’évaluation, `widget` - apparence et comportement du widget, `data_collection` - extraction de données structurées, `overrides` - remplacements pour l’initialisation de la conversation, `workspace_overrides` - configuration des webhooks, `testing` - configurations de test, `safety` - garde-fous (paramètres IVC/non-IVC)
Workflow	Définition complète du workflow (nœuds et arêtes)

Paramètres par agent

Ces paramètres appartiennent à l’agent plutôt qu’à une version, de sorte que toutes les branches les partagent :

Paramètre	Description
`name`, `tags`	Nom et tags de l’agent
`auth`	Paramètres d’authentification et liste d’autorisation
`call_limits`	Limites de requêtes simultanées et limites quotidiennes
`queueing_config`	File d’attente et audio d’attente pour les appelants dépassant la limite de requêtes simultanées
`privacy`	Paramètres de rétention, mode zéro rétention et mémoires utilisateur
`analysis_llm`	LLM utilisé pour l’analyse après appel
`topic_discovery`, `sentiment_analysis`	Paramètres d’analyse au niveau de l’agent
`simulation_library`	Paramètres de la bibliothèque de simulations
`alerting`	Webhooks d’alerte et seuils de surveillance
`ban`	Statut de bannissement (administrateur uniquement)

Les paramètres par agent ne peuvent être modifiés que dans la branche principale. Dans les autres branches, le Dashboard les affiche en lecture seule, et la publication d’une version dans une branche autre que la branche principale ignore toutes les modifications qui leur sont apportées. Les fusionner ensuite dans la branche principale ne les applique pas non plus. Basculez vers la branche principale pour les modifier ; une fois publiées dans celle-ci, les modifications s’appliquent à toutes les branches.

Bonnes pratiques

Créez des tests avant de créer une branche

Configurez des tests automatisés qui capturent le comportement attendu avant de créer une nouvelle branche. Vous établissez ainsi une référence et détectez rapidement les régressions lors des itérations sur votre expérience.

Utilisez des noms de branche descriptifs

Choisissez des noms de branche qui indiquent clairement l’objectif de l’expérience. Incluez le nom de la fonctionnalité, l’hypothèse ou le numéro de ticket pour pouvoir vous y référer facilement (par exemple, feature/new-greeting-flow ou experiment/shorter-responses).

Documentez l’objectif des branches

Utilisez le champ de description de la branche pour expliquer l’hypothèse que vous testez, les métriques qui définissent la réussite, ainsi que les dépendances ou considérations éventuelles. Cela aide les membres de l’équipe à comprendre les expériences en cours.

Utilisez les brouillons pour les travaux en cours

Enregistrez fréquemment des brouillons lorsque vous itérez sur des modifications. Cela préserve votre travail sans créer de versions inutiles. Validez uniquement lorsque vous êtes prêt à tester ou à déployer.

Commencez avec de faibles pourcentages de trafic

Lorsque vous déployez une nouvelle branche, commencez avec 5 à 10 % du trafic. Cela limite l’exposition en cas de problème, tout en fournissant des données utiles.

Surveillez les métriques clés avant d’augmenter le trafic

Utilisez le Dashboard d’analytique pour comparer les performances des branches. Examinez les taux de finalisation des appels, la durée moyenne des conversations, les scores d’évaluation de réussite et les taux d’exécution des outils. N’augmentez le trafic que lorsque les métriques atteignent ou dépassent la référence de votre branche principale.

Augmentez progressivement le trafic

Augmentez le trafic par paliers (10 % → 25 % → 50 % → 100 %) à mesure que votre confiance grandit. Cette approche réduit les risques tout en validant les performances à chaque étape.

Gardez des branches de courte durée

Fusionnez rapidement les expériences concluantes pour éviter une dérive de configuration. Pour les branches qui doivent rester ouvertes plus longtemps, rebasez-les régulièrement sur la branche principale afin qu’elles ne dérivent pas trop et ne deviennent pas plus difficiles à fusionner.

Étapes suivantes

Expériences

Réalisez des tests A/B à l’aide des branches et du déploiement du trafic

Tests

Configurez des tests automatisés pour les versions de vos agents

Analytique

Surveillez les performances des différentes branches

CLI

Gérez le versioning depuis la ligne de commande