Wersjonowanie agenta

Wersjonowanie agenta pozwala eksperymentować z różnymi konfiguracjami agenta bez ryzyka dla konfiguracji produkcyjnej. Twórz odizolowane gałęzie, testuj zmiany i stopniowo wdrażaj aktualizacje przez procentowy podział ruchu.

Omówienie

System wersjonowania oferuje:

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

Kluczowe pojęcia

Wersje

Wersja to niezmienna migawka konfiguracji agenta w określonym momencie. Każda wersja ma unikalne ID (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 oceny, widgetu, 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 z powrotem do gałęzi głównej.

• Każdy wersjonowany agent ma gałąź Main, której nie można usunąć ani zarchiwizować
• Dodatkowe gałęzie można tworzyć z dowolnej wersji w dowolnej istniejącej gałęzi, nie tylko z main
• Gałęzie można scalać z każdą inną gałęzią, a gałęzie inne niż main można rebazować na main, aby pobrać jej 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 wartości procentowych musi zawsze wynosić dokładnie 100%
• Kierowanie ruchu jest deterministyczne na podstawie ID rozmowy (ten sam użytkownik zawsze trafia do tej samej gałęzi)
• Można archiwizować tylko niezarchiwizowane gałęzie z 0% ruchu

Szkice

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

• Szkice są na użytkownika i gałąź (każdy członek zespołu ma własny szkic)
• Szkice są automatycznie odrzucane po zatwierdzeniu nowej wersji
• Szkice są też odrzucane podczas scalania do gałęzi

Włączanie wersjonowania

Wersjonowanie jest opcjonalne i trzeba je włączyć ręcznie. 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ą aktualną konfigurację agenta.

Praca z gałęziami

Tworzenie gałęzi

Gałęzie można tworzyć z dowolnej wersji w dowolnej gałęzi, nie tylko z main. Opcjonalnie możesz uwzględnić 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ący szkic tego użytkownika w tej gałęzi zostaje odrzucony.

Kierowanie ruchu

Użyj endpointu wdrożeń, aby rozdzielić ruch między gałęzie. Pozwala to na 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 ruchem jest deterministyczne na podstawie ID rozmowy, dzięki czemu ten sam użytkownik konsekwentnie trafia do tej samej gałęzi w kolejnych sesjach.

Scalanie gałęzi

Gdy jesteś zadowolony ze zmian w gałęzi, scal je z inną gałęzią. Każdą niearchiwalną gałąź można scalić z dowolną inną niearchiwalną 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 scalania

Jeśli ustawienie zostało zmienione zarówno w gałęzi źródłowej, jak i docelowej od ich rozdzielenia, domyślnie zachowana zostaje wartość z gałęzi aktualizowanej później. Ustaw force=True, aby zawsze użyć wartości 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 gałęzi main do innej gałęzi, podobnie jak git rebase. Pozwala to aktualizować długo działającą gałąź 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 zawiera najnowsze zmiany z main
• Zachowuje własne zmiany gałęzi: jeśli ustawienie zmieniono zarówno w gałęzi, jak i w main, zawsze zachowana 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żesz przywrócić, ustawiając archived=False.

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 w szkicu

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

Ustawienia — informacje

Ustawienia wersjonowane

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

Ustawienia agenta

Te ustawienia są wspólne dla wszystkich wersji:

Dobre praktyki

Kolejne kroki