Versioning des agents

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 d’un déploiement par pourcentage de trafic.

Vue d’ensemble

Le système de versioning fournit :

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

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, au format agtvrsn_xxxx, et contient :

• conversation_config : prompt système, paramètres 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 dans 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, similaires 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 pas être supprimée ni archivée
• Des branches supplémentaires peuvent être créées à partir de n’importe quelle version de toute branche existante, 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 la branche principale pour 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, permettant des déploiements progressifs et des tests A/B.

• Le total des pourcentages doit toujours être exactement de 100 %
• Le routage du trafic est déterministe selon l’ID de conversation, un même utilisateur est donc toujours routé 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 comme brouillons, ce qui vous permet de travailler sur des modifications sans créer immédiatement une nouvelle version.

• Les brouillons sont par utilisateur et par 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 d’une 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.

Activer lors de la création d’un agent

Activer sur un agent existant

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

Utiliser les branches

Créer une branche

Les branches peuvent être créées à partir de n’importe quelle version de toute branche, 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 des modifications

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

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

Déployer le trafic

Utilisez l’endpoint de déploiement 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}
    ]
)

Le routage du trafic est déterministe selon l’ID de conversation, ce qui garantit qu’un même utilisateur accède systématiquement à la même branche au fil des sessions.

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, pas uniquement dans la branche principale.

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

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, indépendamment des 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 main

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

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

Le rebasage :

• Crée une nouvelle version sur la branche qui intègre les dernières modifications de main
• Préserve les propres modifications de la branche : si un paramètre a été modifié à la fois sur la branche et sur main, 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 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. Votre liste de branches reste ainsi organisée.

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

Vous pouvez désarchiver les branches archivées en définissant archived=False.

Récupérer des versions spécifiques

Vous pouvez récupérer un agent à une version spécifique ou à la pointe d’une branche.

Récupérer un agent à une version spécifique

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

Récupérer un agent à la pointe d’une branche

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

Inclure les modifications de 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 :

Paramètres par agent

Ces paramètres sont partagés entre toutes les versions :

Bonnes pratiques

Étapes suivantes