Agent-Versionierung

Mit der Agent-Versionierung können Sie mit verschiedenen Konfigurationen Ihres Agenten experimentieren, ohne Ihre Produktionsumgebung zu gefährden. Erstellen Sie isolierte Branches, testen Sie Änderungen und führen Sie Updates schrittweise über die Traffic-Bereitstellung nach Prozentanteil ein.

Überblick

Das Versionierungssystem bietet:

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

Grundkonzepte

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 Auswertung, 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 Entwicklungszweige, ähnlich wie Git-Branches. Sie ermöglichen es Ihnen, isoliert an Änderungen zu arbeiten, 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 von jeder Version eines bestehenden Branches erstellt werden, nicht nur von Main
• Branches können in jeden anderen Branch gemergt werden. Nicht-Main-Branches können auf Main rebasiert 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 (max. 140 Zeichen)

Traffic-Bereitstellung

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

• Die Prozentwerte müssen immer genau 100 % ergeben
• Das Traffic-Routing ist anhand der Konversations-ID deterministisch (derselbe Nutzer wird konsistent zum selben Branch geleitet)
• 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 sind pro Nutzer und pro Branch (jedes Teammitglied hat einen eigenen Entwurf)
• Entwürfe werden automatisch verworfen, wenn eine neue Version festgeschrieben wird
• Entwürfe werden auch beim Mergen in einen Branch verworfen

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 erste Branch „Main“ mit der ersten Version erstellt, die die aktuelle Agentenkonfiguration enthält.

Mit Branches arbeiten

Einen Branch erstellen

Branches können von jeder Version eines beliebigen Branches erstellt werden, nicht nur von Main. Optional können Sie Konfigurationsänderungen einbeziehen, die auf die erste 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 festschreiben

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

Im angegebenen Branch wird automatisch eine neue Version erstellt. Ein vorhandener Entwurf dieses Nutzers in 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. Dadurch erreicht derselbe Nutzer über verschiedene Sitzungen hinweg konsistent denselben Branch.

Branches mergen

Wenn Sie mit den Änderungen in einem Branch zufrieden sind, mergen Sie sie in einen anderen Branch. Jeder nicht archivierte Branch kann in jeden anderen nicht archivierten Branch gemergt werden, nicht nur in 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 Mergen:

• Wird eine neue Version im Ziel-Branch mit der Konfiguration des Quell-Branches 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, wird standardmäßig der Wert des zuletzt aktualisierten Branches beibehalten. Setzen Sie force=True, um unabhängig von Zeitstempeln immer den Wert des Quell-Branches zu übernehmen.

Sehen Sie sich das Ergebnis eines Merges einschließlich aller Felder, die überschrieben würden, an, bevor Sie ihn festschreiben:

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 Rebasing werden die neuesten Änderungen aus dem Main-Branch in einen anderen Branch übernommen, ähnlich wie bei einem Git-Rebase. So bleibt ein langfristig genutzter Branch auf dem Stand von Main, ohne die eigenen Änderungen des Branches bereits zurückzumergen.

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

Beim Rebasing:

• Wird eine neue Version im Branch erstellt, die die neuesten Änderungen von Main enthält
• Bleiben die eigenen Änderungen des Branches erhalten: Wenn eine Einstellung sowohl im 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 von Main enthält

Sehen Sie sich das Ergebnis eines Rebase an, bevor Sie ihn festschreiben:

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.

Einen versionierten Agenten duplizieren

Beim Duplizieren eines Agenten wird ein neuer Agent erstellt, der eine Kopie jedes nicht archivierten Branches des Quell-Agenten enthält, nicht nur des Main-Branches.

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

Im duplizierten Agenten:

• Wird der Main-Branch aus der neuesten Version im Main-Branch des Quell-Agenten erstellt
• Wird jeder andere nicht archivierte Branch mit demselben Namen und derselben Beschreibung neu erstellt, ausgehend von der neuesten Version in diesem Branch
• Beginnt jeder Branch mit einer einzelnen Version, da der Versionsverlauf nicht kopiert wird
• Werden archivierte Branches und Entwürfe nicht kopiert
• Werden Traffic-Bereitstellungen nicht kopiert. Daher wird der gesamte Traffic an den Main-Branch geleitet, bis Sie Traffic für andere Branches bereitstellen

Branch- und Versions-IDs im Duplikat sind neu. Aktualisieren Sie daher alle Verweise auf die IDs des Quell-Agenten.

Bestimmte Versionen abrufen

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

Agenten mit bestimmter 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
)

Einstellungsreferenz

Versionierte Einstellungen

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

Einstellungen pro Agent

Diese Einstellungen gehören zum Agenten und nicht zu einer Version. Daher teilen sie sich alle Branches:

Best Practices

Nächste Schritte