> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

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

> **Note**
>
> Vous souhaitez réaliser des tests A/B ? Consultez [Expériences](/docs/fr/eleven-agents/operate/experiments) 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

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

> **Warning**
>
> 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

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 via l’API

```python
from elevenlabs.client import ElevenLabs
from elevenlabs.types import *

client = ElevenLabs(api_key="your-api-key")

agent = client.conversational_ai.agents.create(
    conversation_config=ConversationalConfig(
        agent=AgentConfig(
            first_message="Hello! How can I help you today?",
            prompt={"prompt": "You are a helpful assistant."},
        )
    ),
    enable_versioning=True
)

print(f"Agent created with versioning: {agent.agent_id}")
```

```javascript
import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';

const client = new ElevenLabsClient({ apiKey: 'your-api-key' });

const agent = await client.conversationalAi.agents.create({
  conversationConfig: {
    agent: {
      firstMessage: 'Hello! How can I help you today?',
      prompt: {
        prompt: 'You are a helpful assistant.',
      },
    },
  },
  enableVersioning: true,
});

console.log(`Agent created with versioning: ${agent.agentId}`);
```

### Activer sur un agent existant

#### Activer depuis le Dashboard

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

#### Activer via l’API

```python
agent = client.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    enable_versioning_if_not_enabled=True
)
```

```javascript
const agent = await client.conversationalAi.agents.update('agent_7101k5zvyjhmfg983brhmhkd98n6', {
  enableVersioningIfNotEnabled: true,
});
```

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.

```python
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}")
```

```javascript
const branch = await client.conversationalAi.agents.branches.create('agent_7101k5zvyjhmfg983brhmhkd98n6', {
  parentVersionId: 'agtvrsn_xxxx',
  name: 'experiment-v2',
  description: 'Testing new prompt and voice settings',
});

console.log(`Created branch: ${branch.createdBranchId}`);
console.log(`Initial version: ${branch.createdVersionId}`);

```

### Lister les branches

```python
branches = client.conversational_ai.agents.branches.list(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
)

for branch in branches.branches:
print(f"{branch.name}: {branch.id}")

```

```javascript
const branches = await client.conversationalAi.agents.branches.list('agent_7101k5zvyjhmfg983brhmhkd98n6');

for (const branch of branches.branches) {
  console.log(`${branch.name}: ${branch.id}`);
}

```

### Obtenir les détails d’une branche

```python
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)}")

```

```javascript
const branch = await client.conversationalAi.agents.branches.get('agent_7101k5zvyjhmfg983brhmhkd98n6', 'agtbrch_xxxx');

console.log(`Branch: ${branch.name}`);
console.log(`Versions: ${branch.versions.length}`);

```

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

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

#### Mettre à jour via la CLI

Transmettez l’option `--branch` pour effectuer un push vers une branche spécifique par son nom ou son ID. La branche doit déjà exister.

```bash
elevenlabs agents push --agent "<agent-name>" --branch "<branch-name>"
```

#### Mettre à jour via l’API

```python
agent = client.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx",
    conversation_config=ConversationalConfig(
        agent=AgentConfig(
            prompt={"prompt": "You are a friendly customer support agent."},
        )
    )
)
```

```javascript
const agent = await client.conversationalAi.agents.update(
  'agent_7101k5zvyjhmfg983brhmhkd98n6',
  {
    conversationConfig: {
      agent: {
        prompt: {
          prompt: 'You are a friendly customer support agent.',
        },
      },
    },
  },
  { branchId: 'agtbrch_xxxx' }
);
```

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.

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

```javascript
const deployment = await client.conversationalAi.agents.deployments.create('agent_7101k5zvyjhmfg983brhmhkd98n6', {
  deployments: [
    { branchId: 'agtbrch_main', percentage: 90 },
    { branchId: 'agtbrch_xxxx', percentage: 10 },
  ],
});
```

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

> **Note**
>
> 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](/docs/fr/eleven-agents/operate/merge-proposals)
> que d’effectuer la fusion directement.

```python
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
)
```

```javascript
const merge = await client.conversationalAi.agents.branches.merge('agent_7101k5zvyjhmfg983brhmhkd98n6', 'agtbrch_xxxx', {
  targetBranchId: 'agtbrch_main',
  archiveSourceBranch: 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

> **Note**
>
> 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 :

```python
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)
```

```javascript
const preview = await client.conversationalAi.agents.branches.previewMerge('agent_7101k5zvyjhmfg983brhmhkd98n6', 'agtbrch_xxxx', {
  targetBranchId: 'agtbrch_main',
  force: false,
});

console.log(preview.overriddenFields);
console.log(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.

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

```javascript
await client.conversationalAi.agents.branches.rebase('agent_7101k5zvyjhmfg983brhmhkd98n6', '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

> **Note**
>
> 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 :

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

print(preview.overridden_fields)
```

```javascript
const preview = await client.conversationalAi.agents.branches.previewRebase('agent_7101k5zvyjhmfg983brhmhkd98n6', 'agtbrch_xxxx');

console.log(preview.overriddenFields);
```

## Archiver des branches

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

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

```javascript
await client.conversationalAi.agents.branches.update('agent_7101k5zvyjhmfg983brhmhkd98n6', 'agtbrch_xxxx', {
  archived: true,
});
```

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

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

print(duplicate.agent_id)
```

```javascript
const duplicate = await client.conversationalAi.agents.duplicate('agent_7101k5zvyjhmfg983brhmhkd98n6', {
  name: 'Copy of my agent',
});

console.log(duplicate.agentId);
```

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](#deploying-traffic) 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

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

```javascript
const agent = await client.conversationalAi.agents.get('agent_7101k5zvyjhmfg983brhmhkd98n6', {
  versionId: 'agtvrsn_xxxx',
});
```

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

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

```javascript
const agent = await client.conversationalAi.agents.get('agent_7101k5zvyjhmfg983brhmhkd98n6', {
  branchId: 'agtbrch_xxxx',
});
```

### Inclure les modifications du brouillon

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

```javascript
const agent = await client.conversationalAi.agents.get('agent_7101k5zvyjhmfg983brhmhkd98n6', {
  branchId: 'agtbrch_xxxx',
  includeDraft: 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)                                               |

> **Warning**
>
> 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](/docs/fr/eleven-agents/customization/agent-testing) 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](/docs/fr/eleven-agents/dashboard) 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](/docs/fr/eleven-agents/operate/experiments)

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

#### [Tests](/docs/fr/eleven-agents/customization/agent-testing)

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

#### [Analytique](/docs/fr/eleven-agents/dashboard)

Surveillez les performances des différentes branches

#### [CLI](/docs/fr/eleven-agents/operate/cli)

Gérez le versioning depuis la ligne de commande