Versioning degli agenti

Il versioning 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 del traffico in percentuale.

Panoramica

Il sistema di versioning 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 ultime modifiche del branch principale

Concetti chiave

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 soggetto a versioning 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 con versioning attivato. 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 sulle modifiche in isolamento prima di unirle di nuovo al branch principale.

• Ogni agente con versioning ha un branch Main che non può essere eliminato né archiviato
• Puoi creare branch aggiuntivi da qualsiasi versione di qualsiasi branch esistente, non solo da main
• I branch possono essere uniti a qualsiasi altro branch e i branch non-main possono essere sottoposti a rebase su main per includerne le ultime modifiche
• 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 in percentuale tra più branch, consentendo rilasci graduali e test A/B.

• Le percentuali devono sempre totalizzare esattamente 100%
• L’instradamento del traffico è deterministico in base all’ID della conversazione (lo stesso utente viene sempre indirizzato allo stesso branch)
• Possono essere archiviati solo i branch non archiviati con lo 0% di traffico

Bozze

Le modifiche non salvate vengono archiviate come bozze, così puoi 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 eseguito il commit di una nuova versione
• Le bozze vengono eliminate anche quando esegui un merge in un branch

Attivare il versioning

Il versioning è facoltativo e deve essere attivato esplicitamente. Puoi attivarlo quando crei un nuovo agente o per un agente esistente.

Attiva durante la creazione di un agente

Attiva per un agente esistente

L’attivazione del versioning crea il branch iniziale “Main” con la prima versione contenente la configurazione attuale dell’agente.

Lavorare con i branch

Creare un branch

Puoi creare branch da qualsiasi versione di qualsiasi branch, non solo da main. Facoltativamente, puoi includere modifiche alla configurazione che verranno applicate alla versione iniziale del nuovo branch.

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

Elencare i branch

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

Ottenere i dettagli di un branch

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

Eseguire il commit delle modifiche

Quando aggiorni un agente con versioning attivato, specifica branch_id per creare una nuova versione in quel branch.

Una nuova versione viene creata automaticamente 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 rilasci graduali e test 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}
    ]
)

L’instradamento del traffico è deterministico in base all’ID della conversazione, assicurando che lo stesso utente raggiunga sempre lo stesso branch nelle diverse sessioni.

Unire i branch

Quando sei soddisfatto delle modifiche apportate a un branch, uniscile a un altro branch. Puoi unire qualsiasi branch non archiviato a qualsiasi altro branch non archiviato, non solo a main.

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
)

Il merge:

• 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 a quello di destinazione

Risolvere i conflitti di merge

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 l’anteprima del risultato di un merge, inclusi i campi che verrebbero sovrascritti, prima di confermarlo:

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)

Sottoporre i branch a rebase su main

Il rebase trasferisce le ultime modifiche dal branch main a un altro branch, in modo simile a un rebase git. In questo modo, un branch di lunga durata resta aggiornato con main senza ancora unire le modifiche del branch stesso.

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

Il rebase:

• Crea una nuova versione nel branch che incorpora le ultime modifiche di main
• Conserva 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

Visualizza l’anteprima del risultato di un rebase prima di confermarlo:

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

Archiviare i branch

Archivia i branch che non ti servono più. Questo ti aiuta a mantenere organizzato l’elenco dei branch.

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

Puoi ripristinare i branch archiviati impostando archived=False.

Duplicare un agente con versioning

La duplicazione di un agente crea un nuovo agente che contiene una copia di ogni branch non archiviato dell’agente di origine, non solo del branch principale.

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

Nell’agente duplicato:

• Il branch principale viene creato dall’ultima versione del branch principale dell’agente di origine
• Ogni altro branch non archiviato viene ricreato con lo stesso nome e la stessa descrizione, a partire dall’ultima versione di quel branch
• Ogni branch inizia con una sola versione, perché la cronologia delle versioni non viene copiata
• I branch archiviati e le bozze non vengono copiati
• Le distribuzioni del traffico non vengono copiate, quindi tutto il traffico viene indirizzato al branch principale finché non distribuisci il traffico ad altri branch

Gli ID dei branch e delle versioni nel duplicato sono nuovi, quindi aggiorna tutti i riferimenti agli ID dell’agente di origine.

Recuperare versioni specifiche

Puoi recuperare un agente in corrispondenza di una versione specifica o della punta di un branch.

Ottenere l’agente a una versione specifica

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

Ottenere l’agente alla punta del branch

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

Includere le modifiche della bozza

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

Riferimento delle impostazioni

Impostazioni soggette a versioning

Queste impostazioni possono differire tra versioni e branch:

Impostazioni per agente

Queste impostazioni appartengono all’agente anziché a una versione, quindi sono condivise da tutti i branch:

Best practice

Passaggi successivi