에이전트 버전 관리

에이전트 버전 관리를 사용하면 프로덕션 설정을 위험에 노출하지 않고 에이전트의 다양한 구성을 실험할 수 있습니다. 격리된 브랜치를 만들고 변경 사항을 테스트하며, 트래픽 비율 배포를 통해 업데이트를 점진적으로 출시하세요.

개요

버전 관리 시스템은 다음을 제공합니다.

• 언제든지 에이전트 구성의 변경 불가능한 스냅샷
• 실제 운영 전 변경 사항을 테스트하기 위한 격리된 브랜치
• 일정 비율의 사용자에게 변경 사항을 점진적으로 출시하기 위한 트래픽 분할
• 모든 브랜치의 변경 사항을 다른 브랜치로 가져오는 병합
• 최신 Main 브랜치 변경 사항을 브랜치로 가져오는 리베이스

핵심 개념

버전

버전은 특정 시점의 에이전트 구성에 대한 변경 불가능한 스냅샷입니다. 각 버전에는 고유 ID(형식: agtvrsn_xxxx)가 있으며 다음을 포함합니다.

• conversation_config - 시스템 프롬프트, LLM 설정, 음성 구성, 도구, 지식 베이스
• platform_settings - 평가, 위젯, 데이터 수집 및 안전 설정을 포함하는 버전 관리 대상 하위 집합
• workflow - 노드와 엣지를 포함한 전체 워크플로 정의

버전 관리가 활성화된 에이전트에서 변경 사항을 저장하면 버전이 자동으로 생성됩니다. 생성된 버전은 수정할 수 없습니다.

브랜치

브랜치는 git 브랜치와 유사한 이름이 지정된 개발 라인입니다. Main 브랜치에 다시 병합하기 전에 변경 사항을 격리된 환경에서 작업할 수 있습니다.

• 모든 버전 관리 에이전트에는 삭제하거나 아카이브할 수 없는 Main 브랜치가 있습니다
• Main뿐 아니라 기존 브랜치의 모든 버전에서 추가 브랜치를 만들 수 있습니다
• 브랜치는 다른 모든 브랜치에 병합할 수 있으며, Main이 아닌 브랜치는 Main에 리베이스하여 최신 변경 사항을 가져올 수 있습니다
• 각 브랜치에는 id(agtbrch_xxxx), 이름, 설명 및 버전 목록이 있습니다
• 브랜치 이름에는 문자, 숫자 및 () [] {} - / .를 사용할 수 있습니다(최대 140자)

트래픽 배포

트래픽을 비율별로 여러 브랜치에 분할하여 점진적 출시와 A/B 테스트를 지원합니다.

• 비율의 합계는 항상 정확히 100% 여야 합니다
• 트래픽 라우팅은 대화 ID를 기준으로 결정론적으로 수행됩니다(동일한 사용자는 항상 동일한 브랜치로 라우팅됨)
• 트래픽이 0%인 아카이브되지 않은 브랜치만 아카이브할 수 있습니다

초안

저장되지 않은 변경 사항은 초안으로 저장되므로 즉시 새 버전을 만들지 않고도 변경 사항을 작업할 수 있습니다.

• 초안은 사용자별, 브랜치별로 관리됩니다(각 팀원은 자신만의 초안을 가짐)
• 새 버전이 커밋되면 초안은 자동으로 삭제됩니다
• 브랜치에 병합할 때도 초안이 삭제됩니다

버전 관리 활성화

버전 관리는 옵트인 방식이며 명시적으로 활성화해야 합니다. 새 에이전트를 만들 때 또는 기존 에이전트에서 활성화할 수 있습니다.

에이전트 생성 시 활성화

기존 에이전트에서 활성화

버전 관리를 활성화하면 현재 에이전트 구성을 포함하는 첫 번째 버전과 함께 초기 “Main” 브랜치가 생성됩니다.

브랜치 작업

브랜치 만들기

브랜치는 Main뿐 아니라 모든 브랜치의 모든 버전에서 만들 수 있습니다. 새 브랜치의 초기 버전에 적용할 구성 변경 사항을 선택적으로 포함할 수 있습니다.

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 = client.conversational_ai.agents.branches.list(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
)
for branch in branches.branches:
print(f"{branch.name}: {branch.id}")

브랜치 세부 정보 가져오기

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

변경 사항 커밋

버전 관리가 활성화된 에이전트를 업데이트할 때 branch_id를 지정하여 해당 브랜치에 새 버전을 만듭니다.

지정된 브랜치에 새 버전이 자동으로 생성되며, 해당 브랜치에서 해당 사용자가 보유한 기존 초안은 삭제됩니다.

트래픽 배포

배포 엔드포인트를 사용하여 브랜치 간에 트래픽을 분산합니다. 이를 통해 점진적 출시와 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}
    ]
)

트래픽 라우팅은 대화 ID를 기준으로 결정론적으로 수행되므로, 동일한 사용자는 세션 전반에서 일관되게 동일한 브랜치에 연결됩니다.

브랜치 병합

브랜치의 변경 사항에 만족하면 다른 브랜치에 병합하세요. 아카이브되지 않은 브랜치는 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
)

병합 시:

• 소스 브랜치의 구성을 적용한 새 버전이 대상 브랜치에 생성됩니다.
• 선택적으로 소스 브랜치를 아카이브합니다(기본 동작).
• 트래픽이 소스 브랜치에서 대상 브랜치로 자동 전송됩니다.

병합 충돌 해결

분기된 이후 소스 브랜치와 대상 브랜치 모두에서 설정이 변경된 경우, 기본적으로 더 최근에 업데이트된 브랜치의 값이 유지됩니다. 타임스탬프와 관계없이 항상 소스 브랜치의 값을 사용하려면 force=True를 설정하세요.

병합을 확정하기 전에 재정의될 필드를 포함한 병합 결과를 미리 확인하세요.

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)

브랜치를 main에 리베이스하기

리베이스는 git rebase와 유사하게 main 브랜치의 최신 변경 사항을 다른 브랜치로 가져옵니다. 이를 통해 브랜치 자체의 변경 사항을 아직 다시 병합하지 않고도 장기간 유지되는 브랜치를 main과 최신 상태로 유지할 수 있습니다.

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

리베이스 시:

• main의 최신 변경 사항을 반영한 새 버전이 브랜치에 생성됩니다.
• 브랜치 자체의 변경 사항이 유지됩니다. 브랜치와 main 모두에서 설정이 수정된 경우 항상 브랜치의 값이 유지됩니다.
• 브랜치에 main의 모든 변경 사항이 이미 포함되어 있으면 branch_already_up_to_date로 실패합니다.

리베이스를 확정하기 전에 결과를 미리 확인하세요.

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

브랜치 아카이브

더 이상 필요하지 않은 브랜치를 아카이브하세요. 브랜치 목록을 정리하는 데 도움이 됩니다.

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

archived=False를 설정하면 아카이브된 브랜치를 복원할 수 있습니다.

특정 버전 가져오기

특정 버전 또는 브랜치 팁의 에이전트를 가져올 수 있습니다.

특정 버전의 에이전트 가져오기

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

브랜치 팁의 에이전트 가져오기

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

초안 변경 사항 포함

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

설정 레퍼런스

버전별 설정

다음 설정은 버전과 브랜치마다 다를 수 있습니다.

에이전트별 설정

다음 설정은 모든 버전에서 공유됩니다.

모범 사례

다음 단계