Versionshantering för agenter

Versionshantering för agenter gör att du kan experimentera med olika konfigurationer för din agent utan att riskera din produktionskonfiguration. Skapa isolerade grenar, testa ändringar och rulla gradvis ut uppdateringar med trafikdistribution baserad på procentandelar.

Översikt

Versionshanteringssystemet erbjuder:

• Oföränderliga ögonblicksbilder av din agentkonfiguration vid varje tidpunkt
• Isolerade grenar för att testa ändringar innan de går live
• Trafikdelning för att gradvis rulla ut ändringar till en andel av användarna
• Sammanslagning för att föra in ändringar från valfri gren i valfri annan gren
• Rebase för att hämta de senaste ändringarna från huvudgrenen till en gren

Grundläggande begrepp

Versioner

En version är en oföränderlig ögonblicksbild av en agents konfiguration vid en specifik tidpunkt. Varje version har ett unikt ID (format: agtvrsn_xxxx) och innehåller:

• conversation_config - Systemprompt, LLM-inställningar, röstkonfiguration, verktyg, kunskapsbas
• platform_settings - Versionshanterad delmängd som omfattar inställningar för utvärdering, widget, datainsamling och säkerhet
• workflow - Fullständig workflow-definition med noder och kanter

Versioner skapas automatiskt när du sparar ändringar i en versionshanterad agent. När en version har skapats kan den inte ändras.

Grenar

Grenar är namngivna utvecklingslinjer, liknande git-grenar. De låter dig arbeta med ändringar isolerat innan du slår samman dem tillbaka till huvudgrenen.

• Varje versionshanterad agent har en Main-gren som inte kan tas bort eller arkiveras
• Ytterligare grenar kan skapas från valfri version på valfri befintlig gren, inte bara huvudgrenen
• Grenar kan slås samman med valfri annan gren, och andra grenar än huvudgrenen kan rebasas på huvudgrenen för att hämta dess senaste ändringar
• Varje gren har: id (agtbrch_xxxx), namn, beskrivning och en lista över versioner
• Grennamn kan innehålla: bokstäver, siffror och () [] {} - / . (högst 140 tecken)

Trafikdistribution

Trafik kan delas mellan flera grenar efter procentandel, vilket möjliggör gradvisa utrullningar och A/B-testning.

• Procentandelarna måste alltid uppgå till exakt 100 %
• Trafikdirigeringen är deterministisk baserat på konversations-ID:t (samma användare dirigeras konsekvent till samma gren)
• Endast icke-arkiverade grenar med 0 % trafik kan arkiveras

Utkast

Osparade ändringar lagras som utkast, så att du kan arbeta med ändringar utan att omedelbart skapa en ny version.

• Utkast är per användare, per gren (varje teammedlem har sitt eget utkast)
• Utkast kasseras automatiskt när en ny version sparas
• Utkast kasseras också när de slås samman till en gren

Aktivera versionshantering

Versionshantering är valfri och måste aktiveras uttryckligen. Du kan aktivera den när du skapar en ny agent eller för en befintlig agent.

Aktivera när du skapar en agent

Aktivera för en befintlig agent

När du aktiverar versionshantering skapas den första grenen “Main” med den första versionen som innehåller den aktuella agentkonfigurationen.

Arbeta med grenar

Skapa en gren

Grenar kan skapas från valfri version på valfri gren, inte bara huvudgrenen. Du kan valfritt inkludera konfigurationsändringar som tillämpas på den nya grenens första version.

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

Lista grenar

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

Hämta grendetaljer

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

Spara ändringar

När du uppdaterar en agent med versionshantering aktiverad anger du branch_id för att skapa en ny version på den grenen.

En ny version skapas automatiskt på den angivna grenen och eventuella befintliga utkast för den användaren på den grenen kasseras.

Distribuera trafik

Använd distributionsändpunkten för att fördela trafik mellan grenar. Det möjliggör gradvisa utrullningar och A/B-testning.

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

Trafikdirigeringen är deterministisk baserat på konversations-ID:t, vilket säkerställer att samma användare konsekvent når samma gren mellan sessioner.

Sammanfoga grenar

När du är nöjd med ändringarna i en gren kan du sammanfoga dem med en annan gren. Alla icke-arkiverade grenar kan sammanfogas med andra icke-arkiverade grenar, inte bara med 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
)

Sammanfogning:

• Skapar en ny version på målgrenen med källgrenens konfiguration
• Arkiverar valfritt källgrenen (standardbeteende)
• Överför automatiskt trafik från källgrenen till målgrenen

Lösa sammanfogningskonflikter

Om en inställning har ändrats på både käll- och målgrenen sedan de delades upp behålls som standard värdet från den gren som uppdaterades senast. Ange force=True för att alltid använda källgrenens värde i stället, oavsett tidsstämplar.

Förhandsgranska resultatet av en sammanfogning, inklusive eventuella fält som skulle åsidosättas, innan du bekräftar den:

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 av grenar på main

En rebase hämtar de senaste ändringarna från main-grenen till en annan gren, ungefär som git rebase. Det håller en långlivad gren uppdaterad med main utan att ännu sammanfoga grenens egna ändringar tillbaka.

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

Rebase:

• Skapar en ny version på grenen som innehåller mains senaste ändringar
• Bevarar grenens egna ändringar: om en inställning har redigerats både på grenen och i main behålls alltid grenens värde
• Misslyckas med branch_already_up_to_date om grenen redan innehåller alla ändringar från main

Förhandsgranska resultatet av en rebase innan du bekräftar den:

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

Arkivera grenar

Arkivera grenar som du inte längre behöver. Det hjälper dig att hålla grenlistan organiserad.

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

Arkiverade grenar kan avarkiveras genom att ange archived=False.

Hämta specifika versioner

Du kan hämta en agent vid en specifik version eller vid en grentopp.

Hämta agent vid specifik version

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

Hämta agent vid grentopp

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

Inkludera utkaständringar

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

Inställningsreferens

Versionshanterade inställningar

Dessa inställningar kan skilja sig mellan versioner och grenar:

Inställningar per agent

Dessa inställningar delas mellan alla versioner:

Bästa praxis

Nästa steg