프로덕션 AI 에이전트 프롬프트 버전 관리: Sume Format

Sume는 호출이 아니라 레시피에 버전을 매깁니다. Format을 편집할 때마다 version이 올라가고, 모든 실행 영수증에는 실제로 실행된 버전인 format.version이 기록됩니다. 실행을 이전 버전에 고정할 수 없고 롤백 API도 없으므로, 모든 실행의 버전을 로그로 남기고 커밋하는 파일의 사본을 직접 보관하세요.

Format은 백엔드가 이름으로 호출하는 저장된 레시피(SKILL.md와 참고 파일)입니다. 기본 개념은 Sume Format이란?에서 다룹니다. 아래 내용은 2026-09-26에 확인한 Format API (영문), 실행과 결과 (영문), Format 패키지 편집하기에서 가져왔습니다.

무엇이 Format의 새 버전을 만드나요?

모든 편집입니다. Format을 에이전트 대시보드에서 바꿨든, 채팅에서 바꿨든, Contents API로 바꿨든 편집할 때마다 version이 올라갑니다. Contents 쓰기는 Format의 새 패키지 식별값인 commit.tree.sha(Format 레코드가 package_sha로 보고하는 값과 같음)와, 대시보드에 표시되는 카운터인 version으로 응답합니다.

파일 하나에 대한 PUT은 커밋 하나입니다. 패키지 루트에 files 목록을 담아 PUT하면 전부를 커밋 하나, version 증가 하나, 새 package_sha 하나로 쓰므로, 관련된 변경을 한 버전으로 내보낼 수 있습니다.

어떤 버전이 영상을 만들었는지 어떻게 알 수 있나요?

실행 영수증의 format.version을 읽으세요. 실제로 실행된 Format 버전이며, 이후의 편집으로 바뀌지 않습니다. 종료 웹훅에도 같은 영수증이 담기므로, 결과가 도착할 때 버전을 저장할 수 있습니다.

편집하면 이미 진행 중인 실행도 바뀌나요?

바뀌지 않습니다. 패키지 편집은 실행이 아니라 작성이며, 이미 진행 중인 실행에는 영향을 주지 않습니다. 각 실행은 시작할 때의 패키지를 읽습니다.

영수증의 format 객체에는 id, slug, title, version이 담기지만 패키지 sha는 없습니다. 어떤 파일이 영상을 만들었는지 정확히 알아야 한다면, 커밋할 때마다 commit.tree.sha 옆에 version을 기록해 두세요.

실행을 특정 버전에 고정하거나 편집을 롤백할 수 있나요?

현재는 둘 다 할 수 없습니다. 실행 요청에는 버전 필드가 없고, 알 수 없는 최상위 필드는 400 unknown_parameter로 거부됩니다. revert, blame, 히스토리 탐색은 아직 Contents API에 없으며, 공개 git 엔드포인트나 clone URL도 없습니다.

• 편집을 되돌리려면 이전 파일 본문을 다시 커밋하세요. 예전 버전이 돌아오는 것이 아니라 새 커밋이자 새 version이 됩니다.
• API로는 이전 버전의 내용을 볼 수 없으므로, 커밋하는 파일은 여러분의 저장소에 보관하세요.
• 레시피를 다듬는 동안에도 프로덕션에는 고정된 레시피가 필요하다면, 초안은 별도 slug를 가진 두 번째 Format에 두고 프로덕션에서는 안정된 Format만 호출하세요.
• If-Match로 Sume Format 파일 편집하기에서처럼 If-Match와 현재 package_sha로 동시 편집을 막으세요.

버전과 멱등성 키는 어떻게 맞물리나요?

같은 Idempotency-Key와 같은 본문으로 다시 보내면 원래 실행이 돌아옵니다. 두 번째 실행도, 두 번째 과금도 없으므로 처음 실행된 버전이 그대로 보입니다. 키는 Format 하나 단위로 적용됩니다.

문서는 만드는 대상에서 키를 파생하라고 권장합니다. 예를 들어 주문 id에, 일부러 다시 실행하고 싶을 때 올리는 버전을 붙이는 식입니다. Format을 편집한 뒤 새 레시피를 적용하고 싶다면 키의 그 부분을 올리세요. 키 설계는 AI 영상 API 멱등성 키에서 더 다룹니다.