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

# Versionamento degli agenti

Il versionamento degli agenti ti consente di sperimentare diverse configurazioni del tuo agente senza mettere a rischio l'ambiente di produzione. Crea branch isolati, testa le modifiche e distribuisci gradualmente gli aggiornamenti usando la distribuzione percentuale del traffico.

> **Note**
>
> Vuoi eseguire test A/B? Consulta [Esperimenti](/docs/it/eleven-agents/operate/experiments) per il workflow consigliato per testare le modifiche dell'agente sul traffico live.

## Panoramica

Il sistema di versionamento offre:

* **Snapshot immutabili** della configurazione del tuo agente in qualsiasi momento
* **Branch isolati** per testare le modifiche prima della pubblicazione
* **Suddivisione del traffico** per distribuire gradualmente le modifiche a una percentuale di utenti
* **Merge** per trasferire le modifiche da qualsiasi branch a qualsiasi altro branch
* **Rebase** per trasferire in un branch le modifiche più recenti del branch principale

> **Note**
>
> Una volta abilitato il versionamento su un agente, non può essere disabilitato. Tienilo presente prima di abilitare
> il versionamento sugli agenti esistenti.

## Concetti fondamentali

### Versioni

Una versione è uno snapshot immutabile della configurazione di un agente in un momento specifico. Ogni versione ha un ID univoco (formato: `agtvrsn_xxxx`) e contiene:

* `conversation_config` - Prompt di sistema, impostazioni LLM, configurazione della voce, strumenti, knowledge base
* `platform_settings` - Sottoinsieme versionato che include impostazioni di valutazione, widget, raccolta dati e sicurezza
* `workflow` - Definizione completa del workflow con nodi e archi

Le versioni vengono create automaticamente quando salvi le modifiche a un agente versionato. Una volta creata, una versione non può essere modificata.

### Branch

I branch sono linee di sviluppo denominate, simili ai branch git. Ti consentono di lavorare alle modifiche in isolamento prima di unirle di nuovo al branch principale.

* Ogni agente versionato ha un branch **Principale** che non può essere eliminato né archiviato
* Puoi creare branch aggiuntivi da qualsiasi versione di qualsiasi branch esistente, non solo dal branch principale
* I branch possono essere uniti in qualsiasi altro branch e i branch non principali possono essere sottoposti a rebase sul branch principale per riceverne le modifiche più recenti
* Ogni branch ha: ID (`agtbrch_xxxx`), nome, descrizione e un elenco di versioni
* I nomi dei branch possono contenere: lettere, numeri e `() [] {} - / .` (massimo 140 caratteri)

### Distribuzione del traffico

Il traffico può essere suddiviso percentualmente tra più branch, consentendo distribuzioni graduali e test A/B.

* Le percentuali devono sempre totalizzare esattamente **100%**
* Il routing del traffico è **deterministico** in base all'ID della conversazione (lo stesso utente viene indirizzato in modo coerente allo stesso branch)
* Possono essere archiviati solo i branch non archiviati con traffico pari allo 0%

### Bozze

Le modifiche non salvate vengono memorizzate come bozze, consentendoti di lavorare alle modifiche senza creare subito una nuova versione.

* Le bozze sono **per utente e per branch** (ogni membro del team ha la propria bozza)
* Le bozze vengono eliminate automaticamente quando viene effettuato il commit di una nuova versione
* Le bozze vengono eliminate anche quando si esegue il merge in un branch

## Abilitare il versionamento

Il versionamento è facoltativo e deve essere abilitato esplicitamente. Puoi abilitarlo quando crei un nuovo agente o su un agente esistente.

> **Warning**
>
> Una volta abilitato, il versionamento non può essere disabilitato. Si tratta di una modifica permanente al tuo agente.

### Abilitare durante la creazione di un agente

#### Abilita dalla dashboard

Apri il tuo agente nella dashboard, vai su **Impostazioni** e abilita il versionamento. Una volta abilitato, la scheda **Versionamento** diventa disponibile per gestire branch, bozze, versioni e distribuzione del traffico.

#### Abilita tramite 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}`);
```

### Abilitare su un agente esistente

#### Abilita dalla dashboard

Apri il tuo agente nella dashboard, vai su **Impostazioni** e attiva il versionamento.

#### Abilita tramite 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,
});
```

Abilitando il versionamento viene creato il branch iniziale "Principale" con la prima versione contenente la configurazione corrente dell'agente.

## Lavorare con i branch

### Creare un branch

Puoi creare branch da qualsiasi versione di qualsiasi branch, non solo dal branch principale. Puoi includere facoltativamente modifiche alla configurazione che verranno applicate alla versione iniziale del nuovo branch.

```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}`);

```

### Elencare i branch

```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}`);
}

```

### Ottenere i dettagli del branch

```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}`);

```

## Effettuare il commit delle modifiche

Quando aggiorni un agente con il versionamento abilitato, specifica `branch_id` per creare una nuova versione in quel branch.

#### Aggiorna dalla dashboard

Apri la scheda **Versionamento** dell'agente, passa al branch di destinazione, modifica la configurazione e salva per creare una nuova versione.

#### Aggiorna tramite CLI

Passa il flag `--branch` per effettuare il push in un branch specifico in base al nome o all'ID. Il branch deve già esistere.

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

#### Aggiorna tramite 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' }
);
```

Viene creata automaticamente una nuova versione nel branch specificato e qualsiasi bozza esistente per quell'utente in quel branch viene eliminata.

## Distribuire il traffico

Usa l'endpoint deployments per distribuire il traffico tra i branch. Ciò consente distribuzioni graduali e test 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**
>
> Tutte le percentuali devono totalizzare esattamente 100%. La distribuzione non andrà a buon fine in caso contrario.

Il routing del traffico è deterministico in base all'ID della conversazione, assicurando che lo stesso utente raggiunga in modo coerente lo stesso branch tra una sessione e l'altra.

## Unire i branch

Quando sei soddisfatto delle modifiche apportate a un branch, uniscile a un altro branch. Qualsiasi branch non archiviato può essere unito a qualsiasi altro branch non archiviato, non solo a main.

> **Note**
>
> Per far revisionare le modifiche di un branch prima di unirle, oppure per raggiungere un branch per cui non disponi
> dell'accesso in scrittura, apri una [proposta di unione](/docs/it/eleven-agents/operate/merge-proposals) invece di
> eseguire l'unione direttamente.

```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
});
```

L'unione:

* Crea una nuova versione nel branch di destinazione con la configurazione del branch di origine
* Archivia facoltativamente il branch di origine (comportamento predefinito)
* Trasferisce automaticamente il traffico dal branch di origine al branch di destinazione

> **Note**
>
> L'unione non riesce con `no_new_changes_to_merge` se il branch di origine è stato creato dal branch di destinazione
> (e non contiene nuovi commit oltre a quelli del branch di destinazione), e con `branch_already_merged` se è già stato
> unito a quella destinazione.

### Risolvere i conflitti di unione

Se un'impostazione è stata modificata sia nel branch di origine sia in quello di destinazione dopo la loro divergenza, per impostazione predefinita viene mantenuto il valore del branch aggiornato più di recente. Imposta `force=True` per usare sempre il valore del branch di origine, indipendentemente dai timestamp.

Visualizza in anteprima il risultato di un'unione, inclusi i campi che verrebbero sovrascritti, prima di confermarla:

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

## Rebase dei branch su main

Il rebase integra le modifiche più recenti dal branch main in un altro branch, in modo simile a un git rebase. In questo modo un branch a lungo termine rimane aggiornato con main senza unire ancora le modifiche del branch stesso.

```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');
```

Il rebase:

* Crea una nuova versione nel branch che incorpora le modifiche più recenti di main
* Mantiene le modifiche del branch: se un'impostazione è stata modificata sia nel branch sia in main, viene sempre mantenuto il valore del branch
* Non riesce con `branch_already_up_to_date` se il branch include già tutte le modifiche di main

> **Note**
>
> Solo i branch diversi da main possono essere sottoposti a rebase, e solo su main. Il rebase del branch main stesso
> restituisce un errore `cannot_rebase_main`.

Visualizza in anteprima il risultato di un rebase prima di confermarlo:

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

## Archiviare i branch

Archivia i branch che non ti servono più. In questo modo mantieni organizzato l'elenco dei branch.

```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**
>
> Non puoi archiviare un branch a cui è assegnato traffico. Rimuovi tutto il traffico prima di archiviarlo.

Puoi annullare l'archiviazione dei branch impostando `archived=False`.

## Recuperare versioni specifiche

Puoi recuperare un agente a una versione specifica o al tip di un branch.

### Ottenere un agente a una versione specifica

```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',
});
```

### Ottenere un agente al tip del branch

```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',
});
```

### Includere le modifiche in bozza

```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,
});
```

## Riferimento delle impostazioni

### Impostazioni versionate

Queste impostazioni possono variare tra versioni e branch:

| Categoria                                     | Impostazioni                                                                                                                                                                                                                                                                                                                              |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Configurazione della conversazione**        | System prompt, personalità dell'agente, selezione e parametri LLM, impostazioni vocali (modello TTS, ID voce), configurazione degli strumenti, knowledge base, primo messaggio, impostazioni della lingua, rilevamento dei turni, impostazioni delle interruzioni                                                                         |
| **Impostazioni della piattaforma versionate** | `evaluation` - criteri di valutazione, `widget` - aspetto e comportamento del widget, `data_collection` - estrazione di dati strutturati, `overrides` - override per l'avvio della conversazione, `workspace_overrides` - configurazione dei webhook, `testing` - configurazioni di test, `safety` - guardrail (impostazioni IVC/non IVC) |
| **Workflow**                                  | Definizione completa del workflow (nodi e collegamenti)                                                                                                                                                                                                                                                                                   |

### Impostazioni per agente

Queste impostazioni sono condivise tra tutte le versioni:

| Impostazione   | Descrizione                                                        |
| -------------- | ------------------------------------------------------------------ |
| `name`, `tags` | Nome e tag dell'agente (aggiornati solo al commit nel branch main) |
| `auth`         | Impostazioni di autenticazione e allowlist                         |
| `call_limits`  | Limiti di concorrenza e giornalieri                                |
| `privacy`      | Impostazioni di conservazione e modalità senza conservazione       |
| `ban`          | Stato del ban (solo amministratori)                                |

> **Note**
>
> Le modifiche al nome e ai tag nei branch diversi da main non vengono mantenute nell'agente finché non vengono unite a main.

## Best practice

#### Crea test prima di creare un branch

Configura [test automatici](/docs/it/eleven-agents/customization/agent-testing) che acquisiscano il
comportamento previsto prima di creare un nuovo branch. Questo stabilisce una baseline e aiuta a individuare
tempestivamente le regressioni mentre esegui iterazioni sul tuo esperimento.

#### Usa nomi descrittivi per i branch

Scegli nomi di branch che comunichino chiaramente lo scopo dell'esperimento. Includi il nome della funzionalità,
l'ipotesi o il numero del ticket per poterli identificare facilmente (ad esempio, `feature/new-greeting-flow` o
`experiment/shorter-responses`).

#### Documenta lo scopo dei branch

Usa il campo della descrizione del branch per spiegare quale ipotesi stai testando, quali metriche definiscono il
successo e quali dipendenze o aspetti considerare. Questo aiuta i membri del team a comprendere gli
esperimenti attivi.

#### Usa le bozze per i lavori in corso

Salva spesso le bozze mentre apporti modifiche. Così preservi il tuo lavoro senza creare
versioni non necessarie. Esegui il commit solo quando sei pronto a testare o distribuire.

#### Inizia con piccole percentuali di traffico

Quando distribuisci un nuovo branch, inizia con il 5-10% del traffico. Questo limita l'esposizione in caso di problemi,
continuando al contempo a fornire dati significativi.

#### Monitora le metriche chiave prima di aumentare il traffico

Usa la [dashboard di analisi](/docs/it/eleven-agents/dashboard) per confrontare le prestazioni dei branch.
Controlla i tassi di completamento delle chiamate, la durata media delle conversazioni, i punteggi delle valutazioni di successo e
i tassi di esecuzione degli strumenti. Aumenta il traffico solo quando le metriche raggiungono o superano la
baseline del branch main.

#### Aumenta il traffico gradualmente

Aumenta il traffico gradualmente (10% → 25% → 50% → 100%) man mano che cresce la fiducia. Questo approccio
riduce al minimo i rischi, convalidando al contempo le prestazioni in ogni fase.

#### Mantieni i branch attivi per poco tempo

Unisci tempestivamente gli esperimenti riusciti per evitare la deriva della configurazione. Per i branch che devono
rimanere aperti più a lungo, esegui periodicamente il rebase su main, così non si allontanano troppo e non diventano
più difficili da unire.

## Passaggi successivi

#### [Esperimenti](/docs/it/eleven-agents/operate/experiments)

Esegui test A/B usando i branch e la distribuzione del traffico

#### [Test](/docs/it/eleven-agents/customization/agent-testing)

Configura test automatici per le versioni del tuo agente

#### [Analisi](/docs/it/eleven-agents/dashboard)

Monitora le prestazioni nei diversi branch

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

Gestisci il versioning dalla riga di comando