스킬 버전 관리

Agent Registry에서 스킬 버전은 변경 불가능한 버전이 지정된 스킬 패키지의 스냅샷을 나타냅니다. 스킬의 코드나 안내를 업데이트하면 새 버전이 생성됩니다. 이 분리된 아키텍처를 사용하면 스킬의 버전 제어가 가능합니다.

이 문서에서는 스킬 수정 버전을 만들고 관리하는 방법을 설명합니다. 특정 스킬의 기본 버전을 업데이트하는 방법에 대한 자세한 내용은 스킬 메타데이터 또는 기본 버전 업데이트를 참고하세요.

시작하기 전에

시작하기 전에 Agent Registry를 설정하고 독립형 스킬을 등록하세요. 이러한 작업을 실행하려면 프로젝트 ID가 필요합니다.

이 문서에서 Google Cloud CLI 명령어를 사용하려면 gcloud CLI 환경을 설정해야 합니다.

필요한 역할

에이전트 레지스트리에서 스킬 수정사항을 관리하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

다른 Agent Registry 역할에는 스킬 버전 수정사항을 보고, 다운로드하고, 만들고, 업데이트하고, 삭제하는 데 필요한 권한도 포함될 수 있습니다. 자세한 내용은 Agent Registry 역할 및 권한을 참고하세요.

스킬 버전 만들기

새 버전을 만들면 기존 스킬 컨테이너에 새 ZIP 페이로드가 업로드됩니다. 스킬 버전을 만들면 자동으로 스킬의 활성 버전이 됩니다. 하지만 언제든지 스킬의 기본 버전을 업데이트할 수 있습니다. 활성 상태인 버전만 다운로드할 수 있습니다.

스킬의 가격 책정 및 기능 비용에 대한 자세한 내용은 에이전트 레지스트리 가격 책정을 참고하세요.

스킬 수정사항의 최대 ZIP 파일 크기는 500KB입니다.

콘솔

  1. Google Cloud 콘솔에서 Agent Registry 페이지로 이동합니다.

    Agent Registry로 이동

  2. 스킬 탭을 선택하고 스킬 이름을 클릭합니다.
  3. 스킬 세부정보 페이지에서 버전 기록 표를 찾습니다.
  4. 버전 추가를 클릭합니다.

  5. 버전 추가 패널에서 다음 옵션 중 하나를 선택합니다.

    • 파일: 코드 또는 프롬프트 요청 사항 (SKILL.md) 파일이 포함된 패키지 또는 ZIP 파일을 업로드합니다. 찾아보기를 클릭하여 로컬 환경에서 파일을 찾을 수 있습니다.

    • 버킷: 유효한 ZIP 번들이 포함된 Cloud Storage URI (gs://...)를 제공합니다. 찾아보기를 클릭하여 Cloud Storage 버킷에서 파일을 찾을 수 있습니다.

  6. 만들기를 클릭합니다.

스킬 세부정보 페이지의 버전 기록 표에 스킬 버전이 표시됩니다.

gcloud

로컬 ZIP 파일을 업로드하거나 Cloud Storage에 저장된 패키지를 가져와 스킬 수정사항을 만들 수 있습니다.

다음을 바꿉니다.

  • REVISION_ID: 스킬 수정 버전에 할당할 ID입니다.
  • SKILL_ID: 수정에 사용하는 스킬의 ID입니다.
  • PROJECT_ID: 프로젝트 ID입니다.

  • LOCATION: 레지스트리 위치입니다.

  • 로컬 ZIP 파일 업로드: 로컬 ZIP 페이로드를 사용하여 스킬 버전을 만들려면 다음 단계를 따르세요.

    gcloud alpha agent-registry skills revisions create REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --payload="LOCAL_ZIP_PATH"

    LOCAL_ZIP_PATH를 로컬 머신에 있는 패키지 기술 보관 파일의 경로로 바꿉니다.

  • Cloud Storage 버킷에서 가져오기: Cloud Storage 버킷에 호스팅된 ZIP 보관 파일을 사용하여 스킬 수정 버전을 만들려면 다음 단계를 따르세요.

    gcloud alpha agent-registry skills revisions create REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"

    다음을 바꿉니다.

    • BUCKET_NAME: ZIP 번들이 포함된 Cloud Storage 버킷 이름입니다.
    • SKILL_PACKAGE: 스킬 수정사항이 포함된 스킬 패키지의 이름입니다.

REST

스킬 버전을 만들려면 버전 컬렉션에 POST 요청을 전송합니다. ZIP 페이로드를 직접 업로드하거나 Cloud Storage 경로를 지정할 수 있습니다.

  • 로컬 ZIP 파일 업로드: 요청 본문에 base64로 인코딩된 ZIP 바이트가 포함된 archiveUploadSource를 지정합니다. curl에서 인라인 base64 명령어를 사용할 수 있습니다.

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "archiveUploadSource": {
          "archiveContent": "$(base64 -w0 local_skill.zip)"
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions?skillRevisionId=REVISION_ID"

  • Cloud Storage 버킷에서 가져오기: 버킷 경로를 가리키는 요청 본문에 gcsSource를 지정합니다.

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "gcsSource": {
          "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip"
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions?skillRevisionId=REVISION_ID"

다음을 바꿉니다.

  • PROJECT_ID: 프로젝트 ID입니다.
  • LOCATION: 레지스트리 위치입니다.
  • SKILL_ID: 스킬 컨테이너의 ID입니다.
  • REVISION_ID: 이 버전에 할당할 ID입니다.
  • BUCKET_NAME: ZIP이 포함된 Cloud Storage 버킷 이름입니다.
  • SKILL_PACKAGE: ZIP 패키지의 이름입니다.

수정사항 나열 및 설명

스킬의 모든 버전 목록을 확인하고 메타데이터를 검사할 수 있습니다. 스킬의 기본 버전을 업데이트하려면 스킬 메타데이터 또는 기본 버전 업데이트를 참고하세요.

버전을 나열하고 세부정보를 보려면 다음 단계를 따르세요.

콘솔

  1. Google Cloud 콘솔에서 Agent Registry 페이지로 이동합니다.

    Agent Registry로 이동

  2. 스킬 탭을 선택하고 스킬 이름을 클릭합니다.
  3. 스킬 세부정보 페이지에서 버전 기록 표를 찾습니다.
  4. 버전 ID, 생성 시간, 수정 상태, 사용 가능한 작업을 검토합니다.

gcloud

스킬의 모든 수정사항을 나열하려면 다음을 실행합니다.

gcloud alpha agent-registry skills revisions list \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION

특정 버전의 메타데이터를 설명하려면 다음을 실행합니다.

gcloud alpha agent-registry skills revisions describe REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION

REST

버전을 나열하려면 다음을 실행하세요.

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions"

단일 버전의 메타데이터를 가져오려면 다음 단계를 따르세요.

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

버전 페이로드 다운로드

로컬 확인 또는 디버깅을 위해 특정 수정 버전의 컴파일된 ZIP 파일 페이로드를 다운로드할 수 있습니다.

페이로드를 다운로드하려면 다음 두 조건을 모두 충족해야 합니다.

활성 버전의 버전 페이로드를 다운로드하려면 다음 단계를 따르세요.

콘솔

  1. Google Cloud 콘솔에서 Agent Registry 페이지로 이동합니다.

    Agent Registry로 이동

  2. 스킬 탭을 선택하고 스킬 이름을 클릭합니다.
  3. 스킬 세부정보 페이지에서 버전 기록 표를 찾습니다.
  4. 다운로드할 버전을 찾습니다.
  5. 작업 열에서 다운로드를 클릭합니다. ZIP 페이로드가 로컬 머신에 다운로드됩니다.

gcloud

버전의 보관 파일 페이로드를 다운로드하려면 describe 명령어를 --alt=media 플래그와 함께 실행하고 출력을 파일로 리디렉션합니다.

gcloud alpha agent-registry skills revisions describe REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --flags="alt=media" > skill_payload.zip

REST

alt=media 쿼리 매개변수를 추가하여 버전의 리소스 URL에 GET 요청을 보냅니다. HTTP 리디렉션 스트림을 따르려면 curl와 함께 -L 플래그를 사용해야 합니다.

curl -L -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -o skill_payload.zip \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID?alt=media"

특정 버전 삭제

특정 버전을 삭제하면 Agent Registry에서 ZIP 페이로드와 메타데이터 기록이 삭제됩니다.

개별 수정 버전 삭제는 일반적으로 관리자에게만 허용됩니다. 스킬의 기본 버전으로 설정된 버전은 삭제할 수 없습니다. 스킬의 기본 버전을 업데이트하려면 스킬 메타데이터 또는 기본 버전 업데이트를 참고하세요.

특정 버전을 삭제하려면 다음 단계를 따르세요.

콘솔

  1. Google Cloud 콘솔에서 Agent Registry 페이지로 이동합니다.

    Agent Registry로 이동

  2. 스킬 탭을 선택하고 스킬 이름을 클릭합니다.
  3. 스킬 세부정보 페이지에서 버전 기록 표를 찾습니다.
  4. 삭제할 버전을 찾습니다.
  5. 작업 열에서 삭제를 클릭하고 작업을 확인합니다.

gcloud 

gcloud alpha agent-registry skills revisions delete REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION

REST 

curl -X DELETE \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

다음 단계