스킬 등록

Agent Registry를 사용하면 독립형 스킬을 패키징하고 수동으로 등록할 수 있습니다. 독립형 스킬은 에이전트 요청 사항을 관련 메타데이터 애셋 및 선택적 스크립트와 번들로 묶어 에이전트의 추론 및 워크플로를 확장합니다. Agent Registry에 자체 독립형 스킬을 등록하면 Agent Registry를 설정할 때 사용할 수 있는 Google 관리 스킬과 함께 재사용 가능한 기능을 중앙에서 관리, 버전 관리, 공유할 수 있습니다.

시작하기 전에

  1. Agent Registry 설정
  2. 단일 프로젝트 설정의 경우 Agent Registry가 사용 설정된 거버넌스 프로젝트의 프로젝트 ID를 가져옵니다. 여러 프로젝트에 대해 관리 경계를 구성한 경우 경계 전체 검색 및 등록에 관리 프로젝트 ID를 사용하거나 단일 프로젝트 작업에 구성원 프로젝트 ID를 지정합니다.

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

필요한 역할

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

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

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

다른 에이전트 레지스트리 역할에는 기술 및 기술 버전을 등록하고 관리하는 데 필요한 권한이 포함될 수도 있습니다. 자세한 내용은 에이전트 레지스트리 역할 및 권한을 참조하세요.

수집 페이로드 제약 조건

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

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

ENABLED_BLOCKING 또는 ENABLED_NONBLOCKING 스캔 정책을 사용하여 자동 스캔을 사용 설정한 경우 최대 압축 해제 크기를 초과하면 INVALID_ARGUMENT 오류와 함께 버전 생성이 실패하거나 버전의 스캔 상태가 UNSUPPORTED_FORMAT로 전환됩니다. 스캔이 사용 중지되면 에이전트 레지스트리는 이러한 스캔 관련 한도를 우회합니다. 스캔 정책을 구성하고 페이로드 크기 제약조건에 대해 자세히 알아보려면 보안 문제에 대한 스킬 스캔을 참조하세요.

스킬 등록

Agent Registry에 자체 스킬을 수동으로 등록할 수 있습니다. 스킬의 가격 책정 및 기능 비용에 대한 자세한 내용은 Agent Registry 가격 책정을 참조하세요.

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

콘솔

  1. Google Cloud 콘솔에서 에이전트 레지스트리 페이지로 이동합니다.

    에이전트 레지스트리로 이동

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

  3. 기술 탭을 선택합니다.

  4. 스킬 탭에서 스킬 추가 버튼을 클릭하면 스킬 컨테이너를 만들고 초기 스킬 패키지를 가져오는 두 가지 옵션이 표시됩니다. 다음 중 하나를 선택합니다.

    • 스킬 추가: 레지스트리에 새 스킬 컨테이너를 만듭니다. 원하는 경우 스킬 패키지를 업로드하여 첫 번째 버전을 만들 수 있습니다.
    • 스킬 가져오기: SKILL.md 요청 사항 파일과 선택적 스크립트가 포함된 ZIP 번들 또는 독립형 SKILL.md 파일을 업로드하여 새 커스텀 스킬 패키지를 등록합니다.
  5. 기술 만들기 또는 기술 가져오기 패널에서 다음 세부정보를 지정합니다.

    • 표시 이름: 기술의 사용자 친화적인 이름을 입력합니다.
    • 설명: 기술 기능을 설명하는 간단한 요약을 입력합니다.
    • 위치: 지리적 리전을 선택합니다(예: global, us, eu).
  6. 페이로드 소스 섹션에서 다음 중 하나를 선택합니다.

    • 파일: 패키지 또는 파일 업로드 필드에 패키징된 스킬 ZIP 파일 또는 독립형 SKILL.md 파일을 업로드합니다. 최대 업로드 크기는 1MB입니다. 로컬 디렉터리에서 파일을 탐색할 수 있습니다.
    • GCS 버킷: Cloud Storage URI 필드에 Cloud Storage 버킷에 저장된 ZIP 보관 파일의 경로를 입력합니다. 최대 업로드 크기는 1MB입니다. 경로는 gs://BUCKET_NAME/SKILL_PACKAGE.zip 형식이어야 합니다.

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

    스킬은 사용 중지됨(DISABLED) 상태로 생성됩니다. 이후의 모든 기술 작업에서는Google Cloud 콘솔에 표시된 대로 기술을 private-SKILL_ID로 참조합니다.

  8. 에이전트 검색에 스킬을 사용할 수 있도록 하려면 기본 버전을 설정하고 타겟 상태를 활성으로 업데이트합니다. 자세한 내용은 기술 관리를 참고하세요.

gcloud

  1. gcloud agent-registry skills create 명령어를 사용하여 스킬 컨테이너를 만들고 초기 버전 페이로드를 업로드합니다. 로컬 ZIP 파일을 업로드하거나 Cloud Storage에 저장된 패키지를 가져올 수 있습니다.

    • 로컬 ZIP 파일 업로드: 로컬 ZIP 페이로드를 사용하여 스킬을 등록합니다.

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

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

    • Cloud Storage 버킷에서 가져오기: Cloud Storage 버킷에 호스팅된 ZIP 보관 파일을 사용하여 기술을 등록합니다.

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

      다음을 바꿉니다.

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

    두 명령어 중 하나에서 다음을 바꿉니다.

    • SKILL_ID: 기술의 리소스 ID입니다(예: workspace-docs-skill). 생성 후 레지스트리는 private- 프리픽스를 자동으로 앞에 추가합니다. 이후의 모든 기술 명령어에서 프리픽스가 지정된 ID를 사용해야 합니다(예: private-workspace-docs-skill).
    • PROJECT_ID: 프로젝트 ID입니다.
    • LOCATION: 지리적 리전(예: global, us, eu)
    • DISPLAY_NAME: 기술의 사용자 친화적인 이름입니다.
    • DESCRIPTION: 기술 기능을 설명하는 간단한 요약입니다.
  2. 초기 버전 없이 기술을 만들 때는 대상 상태(--target-state)를 draft 또는 disabled로만 설정할 수 있습니다.

    --gcs-source-uri 또는 --payload과 같이 초기 버전으로 스킬을 만들면 Agent Registry에서 초기 버전을 스킬의 기본 버전으로 설정합니다. 스캔 정책에 따라 대상 상태를 다음 값 중 하나로 설정할 수 있습니다.

    • --target-state=active이고 스캔 정책이 disabled 또는 enabled-nonblocking인 경우 생성 작업이 완료되면 기술이 활성(STATE_ACTIVE) 상태로 전환됩니다.
    • --target-state=active이고 스캔 정책이 enabled-blocking(기본값)인 경우 생성 작업이 완료되면 기술이 초안(STATE_DRAFT) 상태로 전환됩니다. 백그라운드에서 보안 스캔이 완료되면 스캔에서 발견 사항이 없고 상위 기술이 초안 상태이고 기본 버전이 여전히 초기 버전을 가리키는 경우에만 상위 기술이 활성(STATE_ACTIVE)으로 전환됩니다.
    • --target-state=disabled 또는 --target-state=draft인 경우 나중에 유효한 기본 버전을 설정하고 대상 상태를 활성으로 업데이트하여 에이전트 검색에 사용할 수 있도록 설정할 수 있습니다. 자세한 내용은 기술 관리를 참조하세요.

REST

  1. 초기 버전 인라인을 사용하여 스킬 컨테이너를 만듭니다.

    HTTP 메서드 및 URL

    POST https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID
    

    다음을 바꿉니다.

    • PROJECT_ID: 프로젝트 ID입니다.
    • LOCATION: 레지스트리 위치입니다.
    • SKILL_ID: 기술 컨테이너의 고유 식별자입니다.

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

    로컬 ZIP 파일 바이트를 직접 업로드하여 스킬을 만들려면 초기 버전(initialRevision)에서 archiveUploadSource 페이로드를 사용합니다. 초기 버전을 제공하면 에이전트 레지스트리에서 해당 버전을 스킬의 기본 버전으로 설정합니다. 목표 상태를 TARGET_STATE_DRAFT, TARGET_STATE_DISABLED 또는 TARGET_STATE_ACTIVE로 설정할 수 있습니다. 초기 버전이 없으면 TARGET_STATE_DRAFT 및 TARGET_STATE_DISABLED만 대상 상태로 지원됩니다.

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

    다음을 바꿉니다.

    • DISPLAY_NAME: 기술의 사용자 친화적인 이름입니다.
    • DESCRIPTION: 기술 기능을 설명하는 간단한 요약입니다.
    • BASE64_ZIP_BYTES: 로컬 ZIP 파일의 base64 인코딩 문자열 표현입니다.

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

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

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

    다음을 바꿉니다.

    • DISPLAY_NAME: 기술의 사용자 친화적인 이름입니다.
    • DESCRIPTION: 기술 기능을 설명하는 간단한 요약입니다.
    • 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_DISABLED",
          "initialRevision": {
            "archiveUploadSource": {
              "archiveContent": "'"$(base64 -w0 local_skill.zip)"'"
            }
          }
        }' \
        "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"
    

    다음을 바꿉니다.

    • DISPLAY_NAME: 기술의 사용자 친화적인 이름입니다.
    • DESCRIPTION: 기술 기능을 설명하는 간단한 요약입니다.
    • PROJECT_ID: 프로젝트 ID입니다.
    • LOCATION: 레지스트리 위치입니다.
    • SKILL_ID: 기술 컨테이너의 고유 식별자입니다.

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

  2. 초기 버전으로 스킬을 만들면 Agent Registry는 초기 버전을 상위 스킬의 기본 버전으로 설정하고 대상 상태 및 스캔 정책에 따라 스킬 상태를 전환합니다.

    • 대상 상태가 TARGET_STATE_ACTIVE이고 스캔 정책이 DISABLED 또는 ENABLED_NONBLOCKING인 경우 장기 실행 작업(LRO)이 완료되면 기술이 STATE_ACTIVE 상태로 전환됩니다.
    • 대상 상태가 TARGET_STATE_ACTIVE이고 스캔 정책이 ENABLED_BLOCKING(기본값)인 경우 LRO가 완료되면 기술이 STATE_DRAFT 상태로 전환됩니다. 백그라운드에서 보안 스캔이 완료되면 스캔에서 발견 사항이 없고 상위 기술이 여전히 STATE_DRAFT에 있고 기본 버전이 여전히 초기 버전을 가리키는 경우에만 상위 기술이 STATE_ACTIVE로 전환됩니다.
    • 대상 상태가 TARGET_STATE_DISABLED 또는 TARGET_STATE_DRAFT인 경우 기술은 STATE_DISABLED 또는 STATE_DRAFT에서 시작됩니다. 나중에 에이전트 검색에 스킬을 사용할 수 있도록 하려면 기본 버전을 설정하고 대상 상태를 TARGET_STATE_ACTIVE로 업데이트해야 합니다. 자세한 내용은 기술 관리를 참조하세요.

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

예를 들어 ID가 workspace-tools인 기술을 만들면 리소스 이름이 projects/PROJECT_NUMBER/locations/LOCATION/skills/private-workspace-tools로 생성됩니다. 기술 식별자는 urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-workspace-tools로 할당됩니다. 모든 후속 기술 작업에 private-workspace-tools 게시 ID를 사용해야 합니다.

스킬을 만들면 Agent Registry가 새 Skill 리소스에 리소스 수준 IAM 허용 정책을 자동으로 구성합니다.

  • 주 구성원에게 스킬에 대한 Agent Registry API 관리자(roles/agentregistry.admin) 역할이 부여됩니다.
  • 프로젝트가 조직에 속하는 경우 프로젝트의 에이전트 워크로드를 나타내는 주 구성원 집합에 기술에 대한 Agent Registry API 뷰어(roles/agentregistry.viewer) 역할이 부여됩니다.

다른 사용자, 그룹, 서비스 계정 또는 에이전트 워크로드와 스킬을 공유하려면 스킬에 대한 액세스 관리를 참조하세요.

다음 단계