Agenten-Versionierung

Die Agenten-Versionierung ermöglicht Ihnen, mit verschiedenen Konfigurationen Ihres Agenten zu experimentieren, ohne Ihre Produktionsumgebung zu gefährden. Erstellen Sie isolierte Branches, testen Sie Änderungen und führen Sie Updates schrittweise per prozentualer Traffic-Auslieferung ein.

Überblick

Das Versionierungssystem bietet:

• Unveränderliche Snapshots Ihrer Agentenkonfiguration zu jedem Zeitpunkt
• Isolierte Branches zum Testen von Änderungen vor dem Go-live
• Traffic-Aufteilung, um Änderungen schrittweise für einen Prozentsatz der Nutzer auszurollen
• Mergen, um Änderungen aus einem beliebigen Branch in einen anderen zu übernehmen
• Rebasing, um die neuesten Änderungen des Main-Branches in einen Branch zu übernehmen

Kernkonzepte

Versionen

Eine Version ist ein unveränderlicher Snapshot der Konfiguration eines Agenten zu einem bestimmten Zeitpunkt. Jede Version hat eine eindeutige ID (Format: agtvrsn_xxxx) und enthält:

• conversation_config - System-Prompt, LLM-Einstellungen, Stimmenkonfiguration, Tools, Wissensdatenbank
• platform_settings - Versionierte Teilmenge mit Einstellungen für Evaluierung, Widget, Datenerfassung und Sicherheit
• workflow - Vollständige Workflow-Definition mit Knoten und Kanten

Versionen werden automatisch erstellt, wenn Sie Änderungen an einem versionierten Agenten speichern. Nach der Erstellung kann eine Version nicht mehr geändert werden.

Branches

Branches sind benannte Entwicklungslinien, ähnlich wie Git-Branches. Sie ermöglichen Ihnen, Änderungen isoliert zu bearbeiten, bevor Sie sie zurück in den Main-Branch mergen.

• Jeder versionierte Agent hat einen Main-Branch, der nicht gelöscht oder archiviert werden kann
• Zusätzliche Branches können aus jeder Version auf jedem bestehenden Branch erstellt werden, nicht nur aus Main
• Branches können in jeden anderen Branch gemergt werden. Nicht-Main-Branches können auf Main rebased werden, um dessen neueste Änderungen zu übernehmen
• Jeder Branch hat: ID (agtbrch_xxxx), Name, Beschreibung und eine Liste von Versionen
• Branch-Namen können Buchstaben, Zahlen und () [] {} - / . enthalten (maximal 140 Zeichen)

Traffic-Auslieferung

Traffic kann prozentual auf mehrere Branches aufgeteilt werden. Dies ermöglicht schrittweise Rollouts und A/B-Tests.

• Die Prozentsätze müssen immer genau 100 % ergeben
• Traffic-Routing ist anhand der Gesprächs-ID deterministisch (derselbe Nutzer wird konsistent demselben Branch zugeordnet)
• Nur nicht archivierte Branches mit 0 % Traffic können archiviert werden

Entwürfe

Nicht gespeicherte Änderungen werden als Entwürfe gespeichert, sodass Sie an Änderungen arbeiten können, ohne sofort eine neue Version zu erstellen.

• Entwürfe gelten pro Nutzer und Branch (jedes Teammitglied hat einen eigenen Entwurf)
• Entwürfe werden automatisch verworfen, wenn eine neue Version festgeschrieben wird
• Entwürfe werden auch verworfen, wenn in einen Branch gemergt wird

Versionierung aktivieren

Die Versionierung ist optional und muss ausdrücklich aktiviert werden. Sie können sie beim Erstellen eines neuen Agenten oder für einen bestehenden Agenten aktivieren.

Beim Erstellen eines Agenten aktivieren

Für einen bestehenden Agenten aktivieren

Durch das Aktivieren der Versionierung wird der initiale Branch „Main“ mit der ersten Version erstellt, die die aktuelle Agentenkonfiguration enthält.

Mit Branches arbeiten

Einen Branch erstellen

Branches können aus jeder Version auf jedem Branch erstellt werden, nicht nur aus Main. Optional können Sie Konfigurationsänderungen einbeziehen, die auf die initiale Version des neuen Branches angewendet werden.

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 auflisten

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

Branch-Details abrufen

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

Änderungen committen

Wenn Sie einen Agenten mit aktivierter Versionierung aktualisieren, geben Sie die branch_id an, um auf diesem Branch eine neue Version zu erstellen.

Auf dem angegebenen Branch wird automatisch eine neue Version erstellt. Ein vorhandener Entwurf dieses Nutzers auf diesem Branch wird verworfen.

Traffic bereitstellen

Verwenden Sie den Deployments-Endpunkt, um Traffic auf Branches zu verteilen. Dies ermöglicht schrittweise Rollouts und A/B-Tests.

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

Das Traffic-Routing ist anhand der Konversations-ID deterministisch. So erreicht derselbe Nutzer über Sitzungen hinweg immer denselben Branch.

Branches zusammenführen

Wenn Sie mit den Änderungen auf einem Branch zufrieden sind, führen Sie sie mit einem anderen Branch zusammen. Jeder nicht archivierte Branch kann mit jedem anderen nicht archivierten Branch zusammengeführt werden, nicht nur mit 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
)

Beim Zusammenführen:

• wird auf dem Ziel-Branch eine neue Version mit der Konfiguration des Quell-Branch erstellt
• wird der Quell-Branch optional archiviert (Standardverhalten)
• wird Traffic automatisch vom Quell-Branch auf den Ziel-Branch übertragen

Merge-Konflikte auflösen

Wenn eine Einstellung seit der Abspaltung sowohl im Quell- als auch im Ziel-Branch geändert wurde, bleibt standardmäßig der Wert des zuletzt aktualisierten Branches erhalten. Setzen Sie force=True, um stattdessen unabhängig von Zeitstempeln immer den Wert des Quell-Branches zu übernehmen.

Zeigen Sie vor dem Commit das Ergebnis eines Merges an, einschließlich aller Felder, die überschrieben würden:

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 auf main rebasen

Beim Rebasen werden die neuesten Änderungen aus dem main-Branch in einen anderen Branch übernommen, ähnlich wie bei einem Git-Rebase. So bleibt ein langlebiger Branch mit main aktuell, ohne die eigenen Änderungen des Branches schon zurückzuführen.

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

Beim Rebasen:

• wird auf dem Branch eine neue Version erstellt, die die neuesten Änderungen von main enthält
• bleiben die eigenen Änderungen des Branches erhalten: Wenn eine Einstellung sowohl auf dem Branch als auch in main bearbeitet wurde, bleibt immer der Wert des Branches erhalten
• schlägt der Vorgang mit branch_already_up_to_date fehl, wenn der Branch bereits alle Änderungen aus main enthält

Zeigen Sie das Ergebnis eines Rebase vor dem Commit an:

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

Branches archivieren

Archivieren Sie Branches, die Sie nicht mehr benötigen. So bleibt Ihre Branch-Liste übersichtlich.

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

Archivierte Branches können durch Setzen von archived=False wiederhergestellt werden.

Bestimmte Versionen abrufen

Sie können einen Agenten in einer bestimmten Version oder an der Spitze eines Branches abrufen.

Agenten in einer bestimmten Version abrufen

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

Agenten an der Branch-Spitze abrufen

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

Entwurfsänderungen einbeziehen

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

Referenz für Einstellungen

Versionierte Einstellungen

Diese Einstellungen können sich zwischen Versionen und Branches unterscheiden:

Einstellungen pro Agent

Diese Einstellungen werden über alle Versionen hinweg geteilt:

Best Practices

Nächste Schritte