Agentversionering

Agentversionering låter dig experimentera med olika konfigurationer för din agent utan att riskera produktionsmiljön. Skapa isolerade grenar, testa ändringar och rulla gradvis ut uppdateringar med trafikdistribution baserad på procentandelar.

Översikt

Versionshanteringssystemet erbjuder:

• Oföränderliga ögonblicksbilder av din agents konfiguration vid varje given tidpunkt
• Isolerade grenar för att testa ändringar innan de tas i bruk
• Trafikdelning för att gradvis rulla ut ändringar till en andel av användarna
• Sammanfogning för att föra in ändringar från valfri gren i en annan gren
• Ombasering för att hämta de senaste ändringarna från huvudgrenen till en gren

Grundläggande koncept

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 deluppsättning som omfattar inställningar för utvärdering, widget, datainsamling och säkerhet
• workflow - Fullständig arbetsflödesdefinition 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 utvecklingsspår, ungefär som git-grenar. De låter dig arbeta med ändringar isolerat innan du sammanfogar dem tillbaka till huvudgrenen.

• Varje versionshanterad agent har en Main-gren som inte kan tas bort eller arkiveras
• Ytterligare grenar kan skapas från vilken version som helst i valfri befintlig gren, inte bara main
• Grenar kan sammanfogas med vilken annan gren som helst, och grenar som inte är main kan ombaseras på main för att hämta dess senaste ändringar
• Varje gren har: id (agtbrch_xxxx), namn, beskrivning och en lista med versioner
• Grennamn kan innehålla: bokstäver, siffror och () [] {} - / . (max 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 sammanlagt bli exakt 100 %
• Trafikroutning är deterministisk baserat på konversations-ID:t (samma användare routas konsekvent till samma gren)
• Endast oarkiverade 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 genomförs
• Utkast kasseras även när du sammanfogar 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 vilken version som helst i valfri gren, inte bara main. Du kan även 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 greninformation

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

Genomföra ändringar

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

En ny version skapas automatiskt i den angivna grenen, och alla befintliga utkast för den användaren i den grenen kasseras.

Distribuera trafik

Använd deployment-slutpunkten 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}
    ]
)

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

Sammanfoga grenar

När du är nöjd med ändringarna i en gren sammanfogar du dem med en annan gren. Alla oarkiverade grenar kan sammanfogas med andra oarkiverade 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 i 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 i både käll- och målgrenen sedan de delades, behålls värdet från den gren som uppdaterades senast som standard. 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 fält som skulle skrivas över, innan du genomför 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)

Ombasera grenar på main

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

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

Ombasering:

• Skapar en ny version i grenen som innehåller de senaste ändringarna från main
• Bevarar grenens egna ändringar: om en inställning redigerades både i grenen och 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 ombasering innan du genomför 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 återställas genom att ange archived=False.

Duplicera en versionshanterad agent

När du duplicerar en agent skapas en ny agent som innehåller en kopia av varje oarkiverad gren i källagenten, inte bara huvudgrenen.

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

I den duplicerade agenten:

• Huvudgrenen skapas från den senaste versionen i källagentens huvudgren
• Varje annan oarkiverad gren återskapas med samma namn och beskrivning, med utgångspunkt i den senaste versionen i den grenen
• Varje gren börjar med en enda version eftersom versionshistoriken inte kopieras
• Arkiverade grenar och utkast kopieras inte
• Trafikdistributioner kopieras inte, så all trafik går till huvudgrenen tills du distribuerar trafik till andra grenar

Gren- och versions-ID:n i dubbletten är nya, så uppdatera alla referenser till källagentens ID:n.

Hämta specifika versioner

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

Hämta agent vid specifik version

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

Hämta agent vid grenspets

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

De här inställningarna hör till agenten snarare än en version, så alla grenar delar dem:

Bästa praxis

Nästa steg