Versiebeheer voor agents

Met versiebeheer voor agents kun je experimenteren met verschillende configuraties van je agent zonder je productieconfiguratie in gevaar te brengen. Maak geïsoleerde branches, test wijzigingen en rol updates geleidelijk uit met deployment op basis van trafficpercentages.

Overzicht

Het versiebeheersysteem biedt:

• Onveranderlijke snapshots van je agentconfiguratie op elk moment
• Geïsoleerde branches om wijzigingen te testen voordat je live gaat
• Trafficverdeling om wijzigingen geleidelijk uit te rollen naar een percentage van de gebruikers
• Mergen om wijzigingen vanuit elke branch naar elke andere branch over te brengen
• Rebasen om de nieuwste wijzigingen van de main branch naar een branch over te halen

Kernconcepten

Versies

Een versie is een onveranderlijke snapshot van de configuratie van een agent op een bepaald moment. Elke versie heeft een unieke ID (indeling: agtvrsn_xxxx) en bevat:

• conversation_config - Systeemprompt, LLM-instellingen, stemconfiguratie, tools, kennisbank
• platform_settings - Versiebeheerde subset met instellingen voor evaluatie, widget, gegevensverzameling en veiligheid
• workflow - Volledige workflowdefinitie met nodes en edges

Versies worden automatisch gemaakt wanneer je wijzigingen opslaat in een agent met versiebeheer. Een versie kan na het maken niet meer worden gewijzigd.

Branches

Branches zijn benoemde ontwikkellijnen, vergelijkbaar met git-branches. Hiermee kun je geïsoleerd aan wijzigingen werken voordat je ze terugmerget naar de main branch.

• Elke agent met versiebeheer heeft een branch Main die niet kan worden verwijderd of gearchiveerd
• Aanvullende branches kunnen worden gemaakt vanuit elke versie op elke bestaande branch, niet alleen vanuit main
• Branches kunnen worden gemerged met elke andere branch en niet-main branches kunnen op main worden gerebased om de nieuwste wijzigingen daarvan op te halen
• Elke branch heeft: id (agtbrch_xxxx), naam, beschrijving en een lijst met versies
• Branchnamen kunnen bevatten: letters, cijfers en () [] {} - / . (maximaal 140 tekens)

Traffic deployment

Traffic kan per percentage worden verdeeld over meerdere branches, wat geleidelijke uitrol en A/B-tests mogelijk maakt.

• Percentages moeten altijd samen precies 100% zijn
• Trafficrouting is deterministisch op basis van de gespreks-ID (dezelfde gebruiker wordt consequent naar dezelfde branch gerouteerd)
• Alleen niet-gearchiveerde branches met 0% traffic kunnen worden gearchiveerd

Concepten

Niet-opgeslagen wijzigingen worden als concepten opgeslagen, zodat je aan wijzigingen kunt werken zonder meteen een nieuwe versie te maken.

• Concepten zijn per gebruiker, per branch (elk teamlid heeft een eigen concept)
• Concepten worden automatisch verwijderd wanneer een nieuwe versie wordt vastgelegd
• Concepten worden ook verwijderd wanneer er naar een branch wordt gemerged

Versiebeheer inschakelen

Versiebeheer is opt-in en moet expliciet worden ingeschakeld. Je kunt het inschakelen bij het maken van een nieuwe agent of voor een bestaande agent.

Inschakelen bij het maken van een agent

Inschakelen voor een bestaande agent

Door versiebeheer in te schakelen, wordt de initiële branch “Main” gemaakt met de eerste versie die de huidige agentconfiguratie bevat.

Werken met branches

Een branch maken

Branches kunnen worden gemaakt vanuit elke versie op elke branch, niet alleen vanuit main. Je kunt optioneel configuratiewijzigingen opnemen die worden toegepast op de initiële versie van de nieuwe 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}")

Branches weergeven

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

Branchdetails ophalen

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

Wijzigingen vastleggen

Wanneer je een agent met ingeschakeld versiebeheer bijwerkt, geef je de branch_id op om een nieuwe versie op die branch te maken.

Er wordt automatisch een nieuwe versie gemaakt op de opgegeven branch en elk bestaand concept van die gebruiker op die branch wordt verwijderd.

Traffic deployen

Gebruik het deployments-endpoint om traffic over branches te verdelen. Hiermee kun je geleidelijk uitrollen en A/B-tests uitvoeren.

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

Trafficrouting is deterministisch op basis van de gespreks-ID, zodat dezelfde gebruiker in verschillende sessies consequent dezelfde branch bereikt.

Branches samenvoegen

Wanneer je tevreden bent met wijzigingen in een branch, voeg je deze samen met een andere branch. Elke niet-gearchiveerde branch kan worden samengevoegd met elke andere niet-gearchiveerde branch, niet alleen met 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
)

Samenvoegen:

• Maakt een nieuwe versie in de doelbranch met de configuratie van de bronbranch
• Archiveert optioneel de bronbranch (standaardgedrag)
• Zet verkeer automatisch over van de bronbranch naar de doelbranch

Mergeconflicten oplossen

Als een instelling in zowel de bron- als doelbranch is gewijzigd sinds ze uiteenliepen, wordt standaard de waarde van de branch die het meest recent is bijgewerkt behouden. Stel force=True in om altijd de waarde van de bronbranch te gebruiken, ongeacht timestamps.

Bekijk het resultaat van een merge vooraf, inclusief alle velden die zouden worden overschreven, voordat je deze vastlegt:

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)

Branches rebasen op main

Rebasen haalt de nieuwste wijzigingen uit de main-branch naar een andere branch, vergelijkbaar met een git rebase. Zo blijft een branch die langere tijd bestaat up-to-date met main zonder de eigen wijzigingen van de branch al terug samen te voegen.

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

Rebasen:

• Maakt een nieuwe versie in de branch waarin de nieuwste wijzigingen van main zijn opgenomen
• Behoudt de eigen wijzigingen van de branch: als een instelling zowel in de branch als in main is bewerkt, blijft altijd de waarde van de branch behouden
• Mislukt met branch_already_up_to_date als de branch al alle wijzigingen uit main bevat

Bekijk het resultaat van een rebase vooraf voordat je deze vastlegt:

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

Branches archiveren

Archiveer branches die je niet langer nodig hebt. Zo houd je je branchlijst overzichtelijk.

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

Je kunt gearchiveerde branches dearchiveren door archived=False in te stellen.

Een geversioneerde agent dupliceren

Door een agent te dupliceren maak je een nieuwe agent die een kopie bevat van elke niet-gearchiveerde branch van de bronagent, niet alleen van de main-branch.

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

In de gedupliceerde agent:

• Wordt de main-branch gemaakt op basis van de nieuwste versie in de main-branch van de bronagent
• Wordt elke andere niet-gearchiveerde branch opnieuw gemaakt met dezelfde naam en beschrijving, vanaf de nieuwste versie in die branch
• Begint elke branch met één versie, omdat de versiegeschiedenis niet wordt gekopieerd
• Worden gearchiveerde branches en concepten niet gekopieerd
• Worden verkeersdeployments niet gekopieerd, waardoor al het verkeer naar de main-branch gaat totdat je verkeer uitrolt naar andere branches

De branch- en versie-ID’s in het duplicaat zijn nieuw, dus werk alle verwijzingen naar de ID’s van de bronagent bij.

Specifieke versies ophalen

Je kunt een agent ophalen bij een specifieke versie of branch tip.

Agent ophalen bij specifieke versie

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

Agent ophalen bij branch tip

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

Conceptwijzigingen opnemen

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

Referentie voor instellingen

Geversioneerde instellingen

Deze instellingen kunnen verschillen tussen versies en branches:

Instellingen per agent

Deze instellingen horen bij de agent in plaats van bij een versie, dus elke branch deelt ze:

Best practices

Volgende stappen