Agent Registry를 사용하면 독립형 스킬을 패키징하고 수동으로 등록할 수 있습니다. 독립형 스킬은 에이전트 요청 사항을 관련 메타데이터 애셋 및 선택적 스크립트와 번들로 묶어 에이전트의 추론 및 워크플로를 확장합니다. Agent Registry에 자체 독립형 스킬을 등록하면 Agent Registry를 설정할 때 사용할 수 있는 Google 관리 스킬과 함께 재사용 가능한 기능을 중앙에서 관리, 버전 관리, 공유할 수 있습니다.
시작하기 전에
- Agent Registry 설정
단일 프로젝트 설정의 경우 Agent Registry가 사용 설정된 거버넌스 프로젝트의 프로젝트 ID를 가져옵니다. 여러 프로젝트에 대해 관리 경계를 구성한 경우 경계 전체 검색 및 등록에 관리 프로젝트 ID를 사용하거나 단일 프로젝트 작업에 구성원 프로젝트 ID를 지정합니다.
이 문서의 Google Cloud CLI 명령어를 사용하려면 gcloud CLI 환경을 설정합니다.
필요한 역할
에이전트 레지스트리에 기술을 등록하는 데 필요한 권한을 얻으려면 관리자에게 에이전트 레지스트리가 사용 설정된 거버넌스 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
-
독립형 스킬 등록 및 관리: 에이전트 레지스트리 사용자(
roles/agentregistry.user) -
독립형 기술 및 기타 Agent Registry 리소스 등록 및 관리:
Agent Registry API 편집자(
roles/agentregistry.editor)
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
다른 에이전트 레지스트리 역할에는 기술 및 기술 버전을 등록하고 관리하는 데 필요한 권한이 포함될 수도 있습니다. 자세한 내용은 에이전트 레지스트리 역할 및 권한을 참조하세요.
수집 페이로드 제약 조건
스킬을 등록하려면 스킬의 소스 파일을 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 가격 책정을 참조하세요.
기술을 등록하려면 다음 단계를 따르세요.
콘솔
Google Cloud 콘솔에서 에이전트 레지스트리 페이지로 이동합니다.
프로젝트 선택기에서 Google Cloud 프로젝트를 선택합니다.
기술 탭을 선택합니다.
스킬 탭에서 스킬 추가 버튼을 클릭하면 스킬 컨테이너를 만들고 초기 스킬 패키지를 가져오는 두 가지 옵션이 표시됩니다. 다음 중 하나를 선택합니다.
- 스킬 추가: 레지스트리에 새 스킬 컨테이너를 만듭니다. 원하는 경우 스킬 패키지를 업로드하여 첫 번째 버전을 만들 수 있습니다.
- 스킬 가져오기:
SKILL.md요청 사항 파일과 선택적 스크립트가 포함된 ZIP 번들 또는 독립형SKILL.md파일을 업로드하여 새 커스텀 스킬 패키지를 등록합니다.
기술 만들기 또는 기술 가져오기 패널에서 다음 세부정보를 지정합니다.
- 표시 이름: 기술의 사용자 친화적인 이름을 입력합니다.
- 설명: 기술 기능을 설명하는 간단한 요약을 입력합니다.
- 위치: 지리적 리전을 선택합니다(예:
global,us,eu).
페이로드 소스 섹션에서 다음 중 하나를 선택합니다.
- 파일: 패키지 또는 파일 업로드 필드에 패키징된 스킬 ZIP 파일 또는 독립형
SKILL.md파일을 업로드합니다. 최대 업로드 크기는 1MB입니다. 로컬 디렉터리에서 파일을 탐색할 수 있습니다. GCS 버킷: Cloud Storage URI 필드에 Cloud Storage 버킷에 저장된 ZIP 보관 파일의 경로를 입력합니다. 최대 업로드 크기는 1MB입니다. 경로는
gs://BUCKET_NAME/SKILL_PACKAGE.zip형식이어야 합니다.
- 파일: 패키지 또는 파일 업로드 필드에 패키징된 스킬 ZIP 파일 또는 독립형
만들기를 클릭합니다.
스킬은 사용 중지됨(
DISABLED) 상태로 생성됩니다. 이후의 모든 기술 작업에서는Google Cloud 콘솔에 표시된 대로 기술을private-SKILL_ID로 참조합니다.에이전트 검색에 스킬을 사용할 수 있도록 하려면 기본 버전을 설정하고 타겟 상태를 활성으로 업데이트합니다. 자세한 내용은 기술 관리를 참고하세요.
gcloud
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: 기술 기능을 설명하는 간단한 요약입니다.
초기 버전 없이 기술을 만들 때는 대상 상태(
--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
초기 버전 인라인을 사용하여 스킬 컨테이너를 만듭니다.
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 본문을 해당 필드 및 값으로 바꿉니다.
초기 버전으로 스킬을 만들면 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) 역할이 부여됩니다.
다른 사용자, 그룹, 서비스 계정 또는 에이전트 워크로드와 스킬을 공유하려면 스킬에 대한 액세스 관리를 참조하세요.
다음 단계
- 등록된 기술을 관리하는 방법을 알아보세요.
- 스킬 버전 추가 및 관리 방법 알아보기
- 보안 문제에 대한 기술을 검사하는 방법을 알아보세요.
- 인증된 게시자 세부정보를 검토합니다.