Wersjonowanie agentów

Wersjonowanie agentów pozwala testować różne konfiguracje agenta bez ryzyka dla środowiska produkcyjnego. Twórz odizolowane gałęzie, testuj zmiany i stopniowo wdrażaj aktualizacje, rozdzielając ruch procentowo.

Omówienie

System wersjonowania oferuje:

• Niezmienne migawki konfiguracji agenta w dowolnym momencie
• Odizolowane gałęzie do testowania zmian przed wdrożeniem
• Podział ruchu, który pozwala stopniowo wdrażać zmiany dla części użytkowników
• Scalanie, aby przenosić zmiany z dowolnej gałęzi do innej gałęzi
• Rebase, aby pobierać najnowsze zmiany z głównej gałęzi do gałęzi

Kluczowe pojęcia

Wersje

Wersja to niezmienna migawka konfiguracji agenta w określonym momencie. Każda wersja ma unikalny identyfikator (format: agtvrsn_xxxx) i zawiera:

• conversation_config - prompt systemowy, ustawienia LLM, konfigurację głosu, narzędzia, bazę wiedzy
• platform_settings - wersjonowany podzbiór obejmujący ustawienia ewaluacji, widżetu, zbierania danych i zabezpieczeń
• workflow - pełną definicję workflow z węzłami i krawędziami

Wersje są tworzone automatycznie, gdy zapisujesz zmiany w wersjonowanym agencie. Po utworzeniu wersji nie można jej zmodyfikować.

Gałęzie

Gałęzie to nazwane linie rozwoju, podobne do gałęzi git. Pozwalają pracować nad zmianami w izolacji przed scaleniem ich z powrotem z główną gałęzią.

• Każdy wersjonowany agent ma gałąź Main, której nie można usunąć ani zarchiwizować
• Dodatkowe gałęzie można tworzyć z dowolnej wersji na dowolnej istniejącej gałęzi, nie tylko z main
• Gałęzie można scalać z dowolną inną gałęzią, a gałęzie inne niż main można rebase’ować na main, aby pobrać najnowsze zmiany
• Każda gałąź ma: id (agtbrch_xxxx), nazwę, opis i listę wersji
• Nazwy gałęzi mogą zawierać: litery, cyfry oraz () [] {} - / . (maks. 140 znaków)

Wdrażanie ruchu

Ruch można dzielić procentowo między wiele gałęzi, co umożliwia stopniowe wdrożenia i testy A/B.

• Suma procentów musi zawsze wynosić dokładnie 100%
• Kierowanie ruchu jest deterministyczne na podstawie identyfikatora rozmowy (ten sam użytkownik jest zawsze kierowany do tej samej gałęzi)
• Można archiwizować tylko niezarchiwizowane gałęzie z 0% ruchu

Wersje robocze

Niezapisane zmiany są przechowywane jako wersje robocze, dzięki czemu możesz nad nimi pracować bez natychmiastowego tworzenia nowej wersji.

• Wersje robocze są na użytkownika i gałąź (każdy członek zespołu ma własną wersję roboczą)
• Wersje robocze są automatycznie odrzucane po zatwierdzeniu nowej wersji
• Wersje robocze są też odrzucane podczas scalania z gałęzią

Włączanie wersjonowania

Wersjonowanie jest opcjonalne i trzeba je wyraźnie włączyć. Możesz je włączyć podczas tworzenia nowego agenta lub dla istniejącego agenta.

Włączanie podczas tworzenia agenta

Włączanie dla istniejącego agenta

Włączenie wersjonowania tworzy początkową gałąź „Main” z pierwszą wersją zawierającą bieżącą konfigurację agenta.

Praca z gałęziami

Tworzenie gałęzi

Gałęzie można tworzyć z dowolnej wersji na dowolnej gałęzi, nie tylko z main. Opcjonalnie możesz dodać zmiany konfiguracji, które zostaną zastosowane w początkowej wersji nowej gałęzi.

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 gałęzi

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

Pobieranie szczegółów gałęzi

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

Zatwierdzanie zmian

Gdy aktualizujesz agenta z włączonym wersjonowaniem, podaj branch_id, aby utworzyć nową wersję w tej gałęzi.

Nowa wersja jest automatycznie tworzona w podanej gałęzi, a istniejąca wersja robocza tego użytkownika w tej gałęzi zostaje odrzucona.

Wdrażanie ruchu

Użyj endpointu wdrożeń, aby rozdzielić ruch między gałęzie. Umożliwia to stopniowe wdrożenia i testy A/B.

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

Kierowanie ruchu jest deterministyczne na podstawie identyfikatora rozmowy, więc ten sam użytkownik zawsze trafia do tej samej gałęzi w różnych sesjach.

Scalanie gałęzi

Gdy zmiany w gałęzi są gotowe, scal je z inną gałęzią. Każdą niezarchiwizowaną gałąź można scalić z dowolną inną niezarchiwizowaną gałęzią, nie tylko z 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
)

Scalanie:

• Tworzy nową wersję w docelowej gałęzi z konfiguracją gałęzi źródłowej
• Opcjonalnie archiwizuje gałąź źródłową (domyślne zachowanie)
• Automatycznie przenosi ruch z gałęzi źródłowej do docelowej

Rozwiązywanie konfliktów scalenia

Jeśli ustawienie zostało zmienione zarówno w gałęzi źródłowej, jak i docelowej od czasu ich rozdzielenia, domyślnie zachowana zostanie wartość z gałęzi aktualizowanej później. Ustaw force=True, aby zawsze wybrać wartość z gałęzi źródłowej, niezależnie od znaczników czasu.

Przed zatwierdzeniem podejrzyj wynik scalenia, w tym pola, które zostałyby nadpisane:

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 gałęzi na main

Rebase pobiera najnowsze zmiany z głównej gałęzi do innej gałęzi, podobnie jak git rebase. Dzięki temu długotrwała gałąź pozostaje aktualna względem main bez scalania z powrotem jej własnych zmian.

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

Rebase:

• Tworzy nową wersję w gałęzi, która uwzględnia najnowsze zmiany z main
• Zachowuje własne zmiany gałęzi: jeśli ustawienie edytowano zarówno w gałęzi, jak i w main, zawsze zostaje wartość z gałęzi
• Kończy się błędem branch_already_up_to_date, jeśli gałąź zawiera już wszystkie zmiany z main

Przed zatwierdzeniem podejrzyj wynik rebase:

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

Archiwizowanie gałęzi

Archiwizuj gałęzie, których już nie potrzebujesz. Dzięki temu lista gałęzi pozostaje uporządkowana.

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

Zarchiwizowane gałęzie można przywrócić, ustawiając archived=False.

Duplikowanie wersjonowanego agenta

Duplikowanie agenta tworzy nowego agenta zawierającego kopię każdej niezarchiwizowanej gałęzi agenta źródłowego, a nie tylko głównej gałęzi.

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

W zduplikowanym agencie:

• Główna gałąź jest tworzona z najnowszej wersji na głównej gałęzi agenta źródłowego
• Każda inna niezarchiwizowana gałąź jest odtwarzana z tą samą nazwą i opisem, zaczynając od najnowszej wersji w tej gałęzi
• Każda gałąź zaczyna z jedną wersją, ponieważ historia wersji nie jest kopiowana
• Zarchiwizowane gałęzie i wersje robocze nie są kopiowane
• Wdrożenia ruchu nie są kopiowane, więc cały ruch trafia do głównej gałęzi, dopóki nie wdrożysz ruchu do innych gałęzi

Identyfikatory gałęzi i wersji w duplikacie są nowe, więc zaktualizuj wszelkie odwołania do identyfikatorów agenta źródłowego.

Pobieranie konkretnych wersji

Możesz pobrać agenta w konkretnej wersji lub na końcu gałęzi.

Pobieranie agenta w konkretnej wersji

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

Pobieranie agenta na końcu gałęzi

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

Uwzględnianie zmian z wersji roboczej

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

Dokumentacja ustawień

Ustawienia wersjonowane

Te ustawienia mogą różnić się między wersjami i gałęziami:

Ustawienia na poziomie agenta

Te ustawienia należą do agenta, a nie do wersji, więc są wspólne dla wszystkich gałęzi:

Dobre praktyki

Kolejne kroki