버전 관리하기

에이전트리아(Agentria)의 어빌리티(Ability)·에이전트(Agent)는 배포 버전(Version) 단위로 변경 이력을 관리합니다. 워크플로를 API로 배포하려면 먼저 이 배포 버전을 생성해야 하므로, 버전 관리는 API 배포를 위한 필수 사전 단계이기도 합니다.

버전 관리가 잘 되어 있으면 다음과 같은 이점이 있습니다.

• 변경 내역을 명확히 추적할 수 있습니다.

• 협업 시 팀원 간 혼선을 줄일 수 있습니다.

• 문제가 발생했을 때 안정적인 이전 버전으로 되돌릴 수 있습니다.

• 사용자에게 신뢰성 있는 업데이트를 제공할 수 있습니다.

이 가이드에서는 버전 번호를 올리는 기준, 실제로 버전을 생성하는 방법, 버전 히스토리를 확인하는 방법, 이전 버전으로 롤백하는 방법을 안내합니다.

버전 관리 기준

에이전트리아의 프로젝트는 유의적 버전(Semantic Versioning)을 따릅니다. (참고: 🔗semver.org)

버전 번호는 주요 버전(Major).부 버전(Minor).수 버전(Patch) 형식으로 구성되며, 각 자리는 아래 기준에 따라 올립니다.

예를 들면 아래와 같이 버전이 올라갑니다.

• 1.4.2 → 1.4.3 (버그 수정)

• 1.4.2 → 1.5.0 (기능 추가)

• 1.4.2 → 2.0.0 (하위 호환성이 깨지는 변경)

1단계: 버전 생성하기

캔버스 우측 상단의 버전(Version) 버튼을 클릭하고, + 아이콘(버전 저장, Create Version)을 클릭합니다.

버전 생성 팝업

팝업창에서 배포 버전을 생성합니다. 위 버전 관리 기준에 따라 버전 번호와 설명을 입력한 뒤 생성(Create) 버튼을 클릭합니다.

2단계: 버전 히스토리 확인하기

생성된 각 버전은 히스토리(History) 탭에서 확인할 수 있습니다.

3단계: 롤백(Rollback)하기

히스토리에서 버전을 선택하면 해당 버전 시점의 노드 구성을 한눈에 확인할 수 있습니다. 이 버전으로 롤백(Rollback to this version) 버튼을 클릭하면 해당 버전으로 되돌아갑니다.

현재 작업 중인 내용에 대해 버전을 생성하지 않은 채로 롤백하면, 작업 중이던 모든 변경 사항과 테스트 이력이 사라지며 되돌릴 수 없습니다. 롤백하기 전에 반드시 현재 상태의 버전을 먼저 생성해 두시기 바랍니다.

다음 단계

버전 생성이 끝났다면, 이제 이 버전을 API로 배포할 수 있습니다.

• 🔗API 배포 가이드 — 생성한 버전을 API 서비스로 배포하는 방법을 확인하세요.

자주 묻는 질문

버전은 언제 새로 생성해야 하나요?

워크플로의 노드 구성이나 로직을 변경한 뒤, 그 시점의 상태를 API로 배포하거나 나중에 되돌아갈 수 있는 지점으로 남기고 싶을 때 새 버전을 생성합니다. 특히 롤백하기 전에는 반드시 현재 상태의 버전을 먼저 생성해 두어야 작업 내용을 잃지 않습니다.

주요·부·수 버전 중 어느 자리를 올려야 할지 헷갈리면 어떻게 하나요?

변경 내용이 기존 사용자의 워크플로나 API 호출을 깨뜨리는지를 먼저 확인합니다. 깨뜨린다면 주요 버전을, 기능만 추가되고 기존 동작은 그대로라면 부 버전을, 동작 방식은 그대로 두고 버그만 고쳤다면 수 버전을 올립니다.

롤백하면 무엇이 사라지나요?

롤백 시점 이후, 즉 마지막으로 생성한 버전 이후에 캔버스에서 변경한 내용과 그 사이의 테스트 이력이 모두 사라지며 복구할 수 없습니다. 롤백 전에 현재 상태를 버전으로 저장해두면 이 문제를 방지할 수 있습니다.

버전 설명은 어떻게 작성하는 게 좋나요?

무엇이 왜 바뀌었는지 팀원이나 미래의 자신이 한눈에 알아볼 수 있도록 간결하게 작성합니다. 예를 들어 "결제 실패 시 재시도 로직 추가", "요약 생성 프롬프트 개선"처럼 변경 내용을 구체적으로 적으면 히스토리에서 원하는 버전을 빠르게 찾을 수 있습니다.