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.

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

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.

Abilitare durante la creazione di un agente

Abilitare su un agente esistente

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.

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

Effettuare il commit delle modifiche

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

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.

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

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.

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
)

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

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:

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)

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.

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

Visualizza in anteprima il 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ù. In questo modo mantieni organizzato l’elenco dei branch.

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

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

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

Ottenere un agente al tip del branch

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

Includere le modifiche in bozza

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

Riferimento delle impostazioni

Impostazioni versionate

Queste impostazioni possono variare tra versioni e branch:

Impostazioni per agente

Queste impostazioni sono condivise tra tutte le versioni:

Best practice

Passaggi successivi