스킬 등록

Agent Registry에서 스킬은 에이전트가 가질 수 있는 독립형 실행 가능 기능을 나타냅니다. 여기에는 SKILL.md 파일의 안내, 코드 스크립트, 에이전트의 추론을 확장하는 애셋이 포함됩니다. Agent Registry에 독립형 스킬을 등록하면 조직의 AI 에이전트 전반에서 기능을 중앙에서 관리하고, 버전을 관리하고, 공유할 수 있습니다.

Google에서 만든 스킬은 Agent Registry를 설정할 때 즉시 표시됩니다. 이 문서에서는 Agent Registry에 자체 독립형 스킬을 수동으로 등록하는 방법을 설명합니다.

시작하기 전에

시작하기 전에 Agent Registry를 설정하세요. 이러한 작업을 수행하려면 프로젝트 ID가 필요합니다.

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

필요한 역할

Agent Registry에 스킬을 등록하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대해 Agent Registry 사용자 (roles/agentregistry.user) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

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

수집 페이로드 제약 조건

스킬을 등록하려면 기능의 소스 파일을 ZIP 보관 파일로 패키징해야 합니다. 보관 파일에는 루트에 SKILL.md 안내 파일이 포함되어야 합니다. 스킬 등록 프로세스의 수집 단계에서 Agent Registry는 페이로드가 다음 제약 조건을 준수하는지 확인합니다.

  • ZIP 보관 파일 크기: 최대 압축 보관 파일 크기는 500KB입니다.
  • 총 압축 해제된 페이로드 크기: 최대 압축 해제된 크기는 10MB입니다.
  • 개별 파일 크기: 파일당 최대 압축 해제된 크기는 1MB입니다.
  • 심층 중첩: 최대 디렉터리 중첩 깊이는 8단계입니다.
  • 사양 준수: SKILL.md 파일에는 에이전트 스킬 사양에 정의된 대로 이름, 설명, 메타데이터를 정의하는 유효한 YAML 프런트 매터 섹션이 포함되어야 합니다.

스킬 등록

Google에서 만든 스킬은 Agent Registry를 설정할 때 즉시 표시됩니다. 하지만 자체 스킬을 수동으로 등록할 수도 있습니다. 각 스킬에는 기본 버전이 있으며 버전이 지정된 여러 스킬 버전이 포함될 수 있습니다.

자체 스킬을 등록하려면 논리적 스킬 컨테이너를 만들고 초기 버전 페이로드를 단일 작업으로 업로드합니다. 나중에 등록된 스킬과 후속 스킬 버전을 관리할 수 있습니다.

사용자 또는 다른 사용자가 만든 스킬은 Google에서 만든 스킬과의 이름 충돌을 방지하기 위해 기본 private 게시자에게 자동으로 할당됩니다. 따라서 특정 스킬의 게시된 ID는 private-SKILL_ID가 됩니다. 스킬을 만드는 동안 커스텀 게시자를 지정할 수 없습니다.

예를 들어 ID가 workspace-tools인 스킬을 만드는 경우 리소스 이름은 projects/PROJECT_ID/locations/LOCATION/skills/private-workspace-tools으로 생성됩니다. 논리적 URN (Uniform Resource Name)은 urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-workspace-tools로 할당됩니다. 후속 스킬 작업에는 모두 이 게시된 ID (private-workspace-tools)를 사용해야 합니다.

스킬을 등록하려면 다음 단계를 따르세요.

콘솔

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

    Agent Registry로 이동

  2. 프로젝트 선택 도구에서 Google Cloud 프로젝트를 선택합니다.

  3. 스킬 탭을 선택합니다.

  4. 스킬 탭에서 스킬 추가 버튼에 두 가지 옵션이 표시됩니다. 다음 중 하나를 선택할 수 있습니다.

    • 스킬 추가: 레지스트리에 새 스킬 컨테이너를 만듭니다. 원하는 경우 스킬 패키지를 업로드하여 첫 번째 버전을 만들 수 있습니다.
    • 스킬 가져오기: 코드 또는 프롬프트 요청 사항 (SKILL.md) 파일이 포함된 ZIP 번들 을 업로드하여 새 커스텀 스킬 패키지를 온보딩합니다.

  5. 스킬 만들기 또는 스킬 가져오기 패널에서 다음 세부정보를 지정합니다.

    • 표시 이름: 스킬의 사용자 친화적인 이름을 입력합니다.
    • 설명: 스킬 기능을 설명하는 간단한 요약을 입력합니다.
    • 위치: 지리적 리전(예: global, us, eu)을 선택합니다.

  6. 페이로드 소스 섹션에서 다음 중 하나를 선택합니다.

    • 파일: 패키징된 스킬 ZIP 파일을 드래그하거나 로컬 디렉터리를 찾아봅니다.

    • 버킷: Cloud Storage 버킷에 저장된 ZIP 보관 파일의 경로를 gs://BUCKET_NAME/SKILL_PACKAGE.zip 형식으로 입력합니다.

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

스킬이 생성됩니다. 후속 스킬 작업에서는 모두Google Cloud 콘솔에 표시된 대로 스킬을 private-SKILL_ID로 참조하세요.

gcloud

스킬을 등록하고 초기 페이로드를 업로드하려면 로컬 ZIP 파일을 업로드하거나 Cloud Storage에 저장된 패키지를 가져오면 됩니다.

다음을 바꿉니다.

  • SKILL_ID: 스킬의 리소스 ID(예: workspace-docs-skill) 생성 후 레지스트리는 자동으로 private- 프리픽스를 앞에 추가합니다. 후속 스킬 명령어(예: private-workspace-docs-skill)에서는 모두 프리픽스가 추가된 ID를 사용해야 합니다.
  • PROJECT_ID: 프로젝트 ID
  • LOCATION: 지리적 리전(예: global, us, eu)
  • DISPLAY_NAME: 스킬의 사용자 친화적인 이름

  • DESCRIPTION: 스킬 기능을 설명하는 간단한 요약

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

    gcloud alpha agent-registry skills create SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --display-name="DISPLAY_NAME" \
  --description="DESCRIPTION" \
  --payload="LOCAL_ZIP_PATH"

    LOCAL_ZIP_PATH를 로컬 머신에 있는 패키징된 스킬 보관 파일의 경로(예: ./workspace-docs-skill.zip)로 바꿉니다.

  • Cloud Storage 버킷에서 가져오기: Cloud Storage 버킷에서 호스팅되는 ZIP 보관 파일을 사용하여 스킬을 등록하려면 다음 단계를 따르세요.

    gcloud alpha agent-registry skills create SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --display-name="DISPLAY_NAME" \
  --description="DESCRIPTION" \
  --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"

    다음을 바꿉니다.

    • BUCKET_NAME: ZIP 번들이 포함된 Cloud Storage 버킷 이름
    • SKILL_PACKAGE: 스킬 페이로드가 포함된 스킬 패키지의 이름

REST

초기 버전이 인라인으로 포함된 스킬을 만들려면 다음 단계를 따르세요.

HTTP 메서드 및 URL

POST https://agentregistry.googleapis.com/v1alpha/projects/{project}/locations/{location}/skills?skillId={skillId}

JSON 요청 본문 (로컬 파일 업로드)

로컬 ZIP 보관 파일 바이트를 직접 업로드하여 스킬을 만들려면 archiveUploadSource 페이로드를 사용합니다.

{
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "type": "SIMPLE",
  "targetState": "TARGET_STATE_ACTIVE",
  "initialRevision": {
    "archiveUploadSource": {
      "archiveContent": "BASE64_ZIP_BYTES"
    }
  }
}

BASE64_ZIP_BYTES를 로컬 ZIP 보관 파일의 base64로 인코딩된 문자열 표현으로 바꿉니다.

JSON 요청 본문 (Cloud Storage에서 가져오기)

또는 Cloud Storage 버킷에 저장된 보관 파일을 사용하여 스킬을 만들려면 gcsSource를 사용합니다.

{
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "type": "SIMPLE",
  "targetState": "TARGET_STATE_ACTIVE",
  "initialRevision": {
    "gcsSource": {
      "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip"
    }
  }
}

다음을 바꿉니다.

  • BUCKET_NAME: ZIP 번들이 포함된 Cloud Storage 버킷 이름
  • SKILL_PACKAGE: 스킬 페이로드가 포함된 스킬 패키지의 이름

curl 명령어 (로컬 파일 업로드)

curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "displayName": "DISPLAY_NAME",
        "description": "DESCRIPTION",
        "type": "SIMPLE",
        "targetState": "TARGET_STATE_ACTIVE",
        "initialRevision": {
          "archiveUploadSource": {
            "archiveContent": "$(base64 -w0 local_skill.zip)"
          }
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"

Cloud Storage 버킷 파일 업로드의 경우 요청 JSON 본문을 해당 필드 및 값으로 바꿉니다.

다음 단계