Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

스킬 버전 관리

에이전트 레지스트리에서 스킬 버전을 사용하면 활성 에이전트를 중단하지 않고 독립형 스킬을 변경할 수 없는 스냅샷으로 버전 제어할 수 있습니다. 각 기술에는 기본 버전이 있으며 여러 버전의 기술 버전이 포함될 수 있습니다. 스킬의 요청 사항 또는 선택적 스크립트를 업데이트할 때 Agent Registry에서 스킬 버전을 만들고, 나열하고, 검사하고, 다운로드하고, 삭제할 수 있습니다. 스킬의 기본 버전을 업데이트하는 방법에 대한 자세한 내용은 스킬 메타데이터 또는 기본 버전 업데이트를 참조하세요.

시작하기 전에

Agent Registry 설정
Agent Registry가 사용 설정된 거버넌스 프로젝트의 프로젝트 ID를 가져옵니다.
독립형 스킬을 등록합니다.
이 문서의 Google Cloud CLI 명령어를 사용하려면 gcloud CLI 환경을 설정합니다.

필요한 역할

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

스킬 버전 나열, 보기, 다운로드: Agent Registry API 뷰어 (roles/agentregistry.viewer)
스킬 버전 만들기, 업데이트, 삭제: 에이전트 레지스트리 사용자 (roles/agentregistry.user)
스킬 버전 및 기타 Agent Registry 리소스 관리: Agent Registry API 편집자 (roles/agentregistry.editor)

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

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

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

스킬 버전 만들기

새 버전을 만들면 새 ZIP 페이로드가 기존 스킬 컨테이너에 업로드됩니다. 검증에 성공하면 버전이 활성 상태로 전환됩니다. 새 버전을 스킬의 기본 버전으로 제공하려면 새 활성 버전을 가리키도록 스킬의 기본 버전을 업데이트합니다. 활성 상태의 버전만 다운로드할 수 있습니다.

스킬의 가격 책정 및 기능 비용에 대한 자세한 내용은 Agent Registry 가격 책정을 참조하세요.

스킬 버전의 최대 ZIP 파일 크기는 500KB입니다.

콘솔

Google Cloud 콘솔에서 에이전트 레지스트리 페이지로 이동합니다.
에이전트 레지스트리로 이동
스킬 탭을 선택하고 스킬 이름을 클릭합니다.
기술 세부정보 페이지에서 버전 기록 표를 찾습니다.
버전 추가를 클릭합니다.
버전 추가 패널에서 다음 옵션 중 하나를 선택합니다.
- 파일: SKILL.md 안내 파일과 선택적 스크립트가 포함된 패키지 또는 ZIP 파일을 업로드합니다. 찾아보기를 클릭하여 로컬 환경에서 파일을 찾을 수 있습니다.
- 버킷: 유효한 ZIP 번들이 포함된 gs://... Cloud Storage URI를 제공합니다. 찾아보기를 클릭하여 Cloud Storage 버킷에서 파일을 찾을 수 있습니다.
  
  중요: Agent Registry가 스킬 파일에 액세스하려면 먼저 Cloud Storage 버킷의 ZIP 파일에 대한 서비스 에이전트 액세스 권한을 부여해야 합니다. 에이전트 레지스트리 서비스 에이전트는 service-PROJECT_NUMBER@gcp-sa-agentregistry.iam.gserviceaccount.com 형식을 사용합니다. 이 서비스 에이전트가 프로젝트에 없으면 Agent Registry API용으로 만듭니다. 자세한 내용은 서비스 에이전트 만들기 및 역할 부여를 참조하세요. 서비스 에이전트에는 ZIP 파일이 포함된 Cloud Storage 버킷에 대한 storage.objects.get 권한이 필요합니다. 버킷 리소스에 Identity and Access Management (IAM) 권한을 부여하는 방법은 Cloud Storage용 IAM을 참조하세요.
만들기를 클릭합니다.

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

gcloud

로컬 ZIP 파일을 업로드하거나 Cloud Storage에 저장된 패키지를 가져와서 기술 버전을 만들 수 있습니다.

다음을 바꿉니다.

REVISION_ID: 기술 버전에 할당할 ID입니다.
SKILL_ID: 버전에 사용 중인 기술의 ID입니다. 수동으로 등록된 기술의 경우 private- 프리픽스(예: private-my-skill)를 포함합니다.
PROJECT_ID: 프로젝트 ID입니다.
LOCATION: 레지스트리 위치입니다.
로컬 ZIP 파일 업로드: 로컬 ZIP 페이로드를 사용하여 기술 버전을 만들려면 gcloud alpha agent-registry skills revisions create 명령어를 실행합니다.
```
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 명령어를 실행합니다.
```
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"
```
중요: Agent Registry가 스킬 파일에 액세스하려면 먼저 서비스 에이전트에 Cloud Storage 버킷의 ZIP 파일에 대한 액세스 권한을 부여해야 합니다. 에이전트 레지스트리 서비스 에이전트는 service-PROJECT_NUMBER@gcp-sa-agentregistry.iam.gserviceaccount.com 형식을 사용합니다. 이 서비스 에이전트가 프로젝트에 없으면 Agent Registry API용으로 만듭니다. 자세한 내용은 서비스 에이전트 만들기 및 역할 부여를 참조하세요. 서비스 에이전트에는 ZIP 파일이 포함된 Cloud Storage 버킷에 대한 storage.objects.get 권한이 필요합니다. 버킷 리소스에 대한 IAM 권한 부여에 대한 안내는 Cloud Storage용 IAM을 참조하세요.

다음을 바꿉니다.
- 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입니다. 수동으로 등록된 기술의 경우 private-my-skill와 같은 private- 프리픽스를 포함합니다.
REVISION_ID: 이 버전에 할당할 ID입니다.
BUCKET_NAME: ZIP이 포함된 Cloud Storage 버킷 이름
SKILL_PACKAGE: ZIP 패키지의 이름입니다.

버전 나열 및 설명

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

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

콘솔

Google Cloud 콘솔에서 에이전트 레지스트리 페이지로 이동합니다.
에이전트 레지스트리로 이동
스킬 탭을 선택하고 스킬 이름을 클릭합니다.
기술 세부정보 페이지에서 버전 기록 표를 찾습니다.
버전 ID, 생성 시간, 버전 상태, 사용 가능한 작업을 검토합니다.

gcloud

스킬의 모든 버전을 나열하려면 gcloud alpha agent-registry skills revisions list 명령어를 실행합니다.

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

특정 버전의 메타데이터를 설명하려면 gcloud alpha agent-registry skills revisions describe 명령어를 실행합니다.

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

다음을 바꿉니다.

SKILL_ID: 기술 컨테이너의 ID입니다. 수동으로 등록된 기술의 경우 private-my-skill와 같은 private- 프리픽스를 포함합니다.
PROJECT_ID: 프로젝트 ID입니다.
LOCATION: 레지스트리 위치입니다.
REVISION_ID: 기술 버전의 ID입니다.

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"

다음을 바꿉니다.

PROJECT_ID: 프로젝트 ID입니다.
LOCATION: 레지스트리 위치입니다.
SKILL_ID: 기술 컨테이너의 ID입니다. 수동으로 등록된 기술의 경우 private-my-skill와 같은 private- 프리픽스를 포함합니다.
REVISION_ID: 기술 버전의 ID입니다.

버전 페이로드 다운로드

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

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

스킬: 스킬은 활성 또는 지원 중단됨 상태여야 합니다. 스킬의 타겟 상태를 변경하려면 스킬 수명 주기 상태 관리를 참조하세요.
스킬 버전: 버전이 활성 상태여야 합니다. 실패 또는 생성 중 상태의 버전은 다운로드할 수 없습니다. 스킬 버전 상태를 검토하려면 버전을 나열하고 설명합니다.

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

콘솔

Google Cloud 콘솔에서 에이전트 레지스트리 페이지로 이동합니다.
에이전트 레지스트리로 이동
스킬 탭을 선택하고 스킬 이름을 클릭합니다.
기술 세부정보 페이지에서 버전 기록 표를 찾습니다.
다운로드할 버전을 찾습니다.
작업 열에서 다운로드를 클릭합니다. ZIP 페이로드가 로컬 머신에 다운로드됩니다.

gcloud

버전의 보관 파일 페이로드를 다운로드하려면 gcloud alpha agent-registry skills revisions download 명령어를 실행하고 대상 경로를 지정합니다.

gcloud alpha agent-registry skills revisions download REVISION_ID \
    --skill=SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --destination="./skill_payload.zip"

다음을 바꿉니다.

REVISION_ID: 다운로드할 기술 버전의 ID입니다.
SKILL_ID: 기술 컨테이너의 ID입니다. 수동으로 등록된 기술의 경우 private-my-skill와 같은 private- 프리픽스를 포함합니다.
PROJECT_ID: 프로젝트 ID입니다.
LOCATION: 레지스트리 위치입니다.

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"

다음을 바꿉니다.

PROJECT_ID: 프로젝트 ID입니다.
LOCATION: 레지스트리 위치입니다.
SKILL_ID: 기술 컨테이너의 ID입니다. 수동으로 등록된 기술의 경우 private-my-skill와 같은 private- 프리픽스를 포함합니다.
REVISION_ID: 다운로드할 기술 버전의 ID입니다.

특정 버전 삭제

특정 버전을 삭제하면 에이전트 레지스트리에서 ZIP 페이로드 및 메타데이터 기록이 삭제됩니다.

개별 버전 삭제는 일반적으로 관리자로 제한됩니다. 스킬의 기본 버전으로 설정된 버전을 삭제하면 Agent Registry가 defaultRevision 포인터를 지우고 활성 스킬을 사용 중지됨 상태로 전환합니다. 스킬을 활성 상태로 유지하려면 이전 기본 버전을 삭제하기 전에 다른 활성 버전을 가리키도록 스킬의 기본 버전을 업데이트합니다.

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

콘솔

Google Cloud 콘솔에서 에이전트 레지스트리 페이지로 이동합니다.
에이전트 레지스트리로 이동
스킬 탭을 선택하고 스킬 이름을 클릭합니다.
기술 세부정보 페이지에서 버전 기록 표를 찾습니다.
삭제할 버전을 찾습니다.
작업 열에서 삭제를 클릭하고 작업을 확인합니다.

gcloud

버전을 삭제하려면 gcloud alpha agent-registry skills revisions delete 명령어를 실행합니다.

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

다음을 바꿉니다.

REVISION_ID: 삭제할 기술 버전의 ID입니다.
SKILL_ID: 기술 컨테이너의 ID입니다. 수동으로 등록된 기술의 경우 private-my-skill와 같은 private- 프리픽스를 포함합니다.
PROJECT_ID: 프로젝트 ID입니다.
LOCATION: 레지스트리 위치입니다.

REST

버전을 삭제하려면 DELETE 요청을 보냅니다.

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"

다음을 바꿉니다.

PROJECT_ID: 프로젝트 ID입니다.
LOCATION: 레지스트리 위치입니다.
SKILL_ID: 기술 컨테이너의 ID입니다. 수동으로 등록된 기술의 경우 private-my-skill와 같은 private- 프리픽스를 포함합니다.
REVISION_ID: 삭제할 기술 버전의 ID입니다.

다음 단계

인증된 게시자를 탐색하는 방법을 알아보세요.
스킬 버전의 할당량 및 한도를 이해합니다.

스킬 버전 관리 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

필요한 역할

스킬 버전 만들기

콘솔

gcloud

REST

버전 나열 및 설명

콘솔

gcloud

REST

버전 페이로드 다운로드

콘솔

gcloud

REST

특정 버전 삭제

콘솔

gcloud

REST

다음 단계

스킬 버전 관리