에이전트 레지스트리에서 스킬을 사용하면 요청 사항, 선택적 스크립트, 도메인 지식을 에이전트의 추론 및 워크플로를 확장하는 모듈식 기능으로 패키징할 수 있습니다. Agent Registry에 독립형 스킬을 등록하면 에이전트 전반에서 재사용 가능한 작업 로직을 중앙에서 버전 관리, 제어, 공유할 수 있습니다. 에이전트 레지스트리는 에이전트의 에이전트 카드에 선언된 인라인 A2A 기술의 색인도 생성하므로 다른 에이전트가 이를 검색하고 호출할 수 있습니다.
스킬 유형
에이전트 레지스트리는 두 가지 유형의 기술을 지원합니다.
- 독립형 기술: Agent Registry에 최상위
Skill리소스로 등록된 버전 제어 패키지입니다. 독립형 기술에는 단일 에이전트 배포와 독립적으로 관리되는SKILL.md요청 사항 파일, 선택적 스크립트, 메타데이터 애셋이 포함됩니다. - A2A 기술: 에이전트의
agent-card.json에이전트 카드의skills필드에 인라인으로 나열된 기능 설명으로, 다른 에이전트에게 작업을 위임하는 시기와 방법을 알려줍니다.
이 두 모델을 비교하려면 독립형 기술과 A2A 기술의 차이점을 참고하세요.
독립형 스킬
독립형 기술은 에이전트 레지스트리의 최상위 리소스로, 에이전트, MCP 서버, 엔드포인트와 함께 관리됩니다. 이러한 구성요소와 달리 독립형 기술은 별도의 Service 리소스를 사용하지 않습니다.
대신 다음 세 가지 리소스 수준에서 독립형 기술을 직접 등록, 버전 관리, 쿼리합니다.
- 게시자: 기술 모음의 소유권, 인증 등급, 기술 식별자 문법을 설정하는
Publisher리소스입니다. - 기술 컨테이너: 소비자가 런타임에 검색하고 확인하는 에이전트 레지스트리의 최상위
Skill리소스로, 각 리소스는 기술의 기본 서빙 버전에 대한 포인터를 유지합니다. - 스킬 버전: 특정 버전의 스킬 패키지 안내, 선택적 스크립트, 메타데이터 애셋이 포함된 변경 불가능한 읽기 전용
SkillRevision리소스입니다.
게시자
Agent Registry의 모든 독립형 스킬은 게시자에 속합니다. 게시자는 기술의 출처, 인증 등급, 이름 지정 프리픽스를 설정합니다.
- Google 관리 게시자(
FIRST_PARTY): Google에서 관리하는 인증된 게시자입니다(예:cloud.google.com및discoveryengine.googleapis.com). 에이전트 레지스트리를 설정하고 다음 스킬 식별자 형식(urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID)을 사용하면 이러한 게시자의 Google 관리 스킬을 모든 프로젝트에서 검색할 수 있습니다. 예를 들면urn:skill:discoveryengine.googleapis.com:discoveryengine:report-writing입니다. - 비공개 게시자 (
PRIVATE): Google Cloud 거버넌스 프로젝트 내에서 수동으로 등록하는 커스텀 기술에 자동으로 할당되는 기본private게시자입니다. 확인된 Google 관리 스킬과의 이름 충돌을 방지하기 위해 에이전트 레지스트리는 스킬 식별자 앞에private-프리픽스를 자동으로 추가합니다. 커스텀Publisher리소스를 등록할 수 없습니다. 비공개 기술은 기술 식별자에urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-SKILL_ID과 같은 Uniform Resource Name (URN) 형식을 사용합니다. 예를 들면urn:skill:projects-PROJECT_NUMBER:locations:global:private-incident-triage입니다.
게시자를 검사하는 방법은 기술 게시자 세부정보 검토를 참고하세요.
기술 컨테이너
스킬 컨테이너는 거버넌스 프로젝트 및 위치 내에서 독립형 스킬을 나타내는 Skill 리소스입니다. 수동으로 만든 기술의 경우 에이전트 레지스트리는 projects/PROJECT_NUMBER/locations/LOCATION/skills/private-SKILL_ID 형식으로 리소스 이름을 생성합니다.
Skill 리소스는 에이전트 레지스트리에서 검색을 위한 안정적인 참조 지점 역할을 하며 다음 필드를 유지합니다.
- 설명 메타데이터: 사람이 읽을 수 있는 표시 이름 (
displayName), 요약 설명 (description), 기술 식별자(skillId), 게시자 저작자 표시입니다. - 기본 버전 포인터: 소비자가 명시적 버전 ID를 요청하지 않고 스킬을 확인하거나 다운로드할 때 제공되는 특정
SkillRevision리소스를 참조하는defaultRevision필드입니다. - 대상 수명 주기 상태: 기술이 활성, 사용 중지, 지원 중단 또는 사용 중단 상태인지 여부를 제어하는
targetState필드입니다.
스킬을 보고 업데이트하는 방법은 스킬 관리를 참조하세요.
스킬 버전
스킬 버전 (SkillRevision) 리소스는 스킬 패키지의 변경할 수 없는 버전이 지정된 스냅샷을 나타냅니다. 리소스 이름은 projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID 형식입니다.
스킬의 안내, 선택적 스크립트 또는 메타데이터 애셋을 업데이트할 때 기존 패키지를 수정하지 않습니다. 대신 새 ZIP 보관 파일을 업로드하여 새 버전을 만듭니다. Agent Registry에서 보관 파일이 에이전트 스킬 사양 및 수집 페이로드 제약 조건을 충족하는지 검증하면 버전이 활성 (ACTIVE) 상태로 전환됩니다. 그런 다음 상위 기술에서 기본 버전 포인터를 업데이트하여 새 버전을 제공할 수 있습니다. 스킬의 기본 버전으로 설정된 버전을 삭제하면 Agent Registry가 defaultRevision 포인터를 지우고 활성 스킬을 사용 중지됨(DISABLED) 상태로 전환합니다.
스킬 컨테이너를 스킬 버전 스냅샷에서 분리하면 다음과 같은 이점이 있습니다.
- 결정론적 실행: 특정 버전에 고정된 에이전트는 예기치 않은 프롬프트 변경이나 스크립트 업데이트로부터 보호됩니다.
- 제어된 롤백: 새 기술 버전을 업로드하고 확인하거나 문제가 발생하면
defaultRevision포인터를 이전 버전으로 되돌릴 수 있습니다. - 감사 가능성: 기술 패키지의 이전 버전은 명시적으로 삭제될 때까지 보존되고 검사할 수 있습니다.
버전 업로드, 다운로드, 삭제에 대한 안내는 스킬 버전 관리를 참조하세요.
패키지 사양
독립형 스킬은 개방형 표준 에이전트 스킬 사양을 준수하는 ZIP 파일로 패키징됩니다.
보관 파일에는 루트에 SKILL.md 파일과 기술에 필요한 스크립트 또는 메타데이터 애셋이 포함되어야 합니다. SKILL.md 파일은 스킬의 안내를 정의합니다. 이 파일은 name 및 description과 같은 YAML 프런트 매터 메타데이터를 Agent Runtime에서 해석하는 자연어 안내와 결합하고 보관 파일의 선택적 스크립트 또는 지원 애셋을 참조합니다.
스킬을 등록하거나 버전을 만들면 에이전트 레지스트리가 수집 페이로드 제약 조건에 따라 보관 파일을 검증하고, SKILL.md 파일을 파싱하고, 검색 및 탐색을 위해 메타데이터의 색인을 생성합니다.
스킬 수명 주기 상태
런타임 시 독립형 기술이 확인되고 다운로드되는 방식을 제어하려면 기술 컨테이너의 targetState를 다음 네 가지 상태로 전환하면 됩니다.
- 활성 (
ACTIVE): 기술이 제공되고, 탐색을 위해 색인이 생성되며, 런타임 확인 및 페이로드 다운로드에 사용할 수 있습니다. 스킬을 활성으로 설정하려면defaultRevision포인터가 활성SkillRevision리소스를 참조해야 합니다. - 사용 중지됨 (
DISABLED): 기술이 생성될 때의 기본 초기 상태입니다. 스킬은 런타임에 제공되지 않으며 확인 및 페이로드 다운로드가 즉시 실패합니다.defaultRevision포인터가 삭제되거나 기본 버전이 삭제되면 기술이 사용 중지됨 상태로 전환됩니다. 사용 중지됨 상태와 달리 유효한defaultRevision를 설정하고 대상 상태를 활성으로 업데이트하여 사용 중지된 기술을 사용 설정할 수 있습니다. - 지원 중단됨 (
DEPRECATED): 스킬을 계속 확인하고 다운로드할 수 있지만 소비자에게 사용 중단될 예정임을 나타냅니다. - 사용 중지됨 (
DECOMMISSIONED): 기술이 영구적으로 비활성화되고 더 이상 제공되지 않으며 활성 또는 다른 상태로 되돌릴 수 없는 최종 상태입니다. 스킬은 지원 중단된 후에만 사용 중지할 수 있습니다.
이전 버전을 삭제하지 않고 Google Cloud 콘솔, Google Cloud CLI 또는 Agent Registry API를 사용하여 기술의 수명 주기 상태를 업데이트할 수 있습니다. 버전의 ZIP 페이로드를 다운로드하려면 상위 기술이 활성 또는 지원 중단됨 상태여야 하고 버전 자체가 활성 상태여야 합니다. 단계별 안내는 스킬 수명 주기 상태 관리를 참조하세요.
독립형 기술과 A2A 기술의 차이점
에이전트 레지스트리는 독립형 기술과 인라인 A2A 기술을 모두 지원합니다. 다음 표에서는 특성을 비교합니다.
| 특성 | 독립형 스킬 | 인라인 A2A 기술 |
|---|---|---|
| 리소스 유형 | 하위 SkillRevision 리소스가 있는 Agent Registry의 최상위 Skill 리소스입니다. |
Agent 리소스 내의 중첩 배열입니다. |
| 패키지 콘텐츠 | SKILL.md, 선택적 스크립트, 지원 애셋이 포함된 ZIP 파일 |
id, name, description가 포함된 에이전트 카드의 JSON 객체입니다. |
| 버전 관리 모델 | 구성 가능한 defaultRevision 포인터가 있는 변경 불가능한 기술 버전 스냅샷입니다. |
에이전트의 agent-card.json 업데이트에 직접 연결됩니다. |
| 실행 모델 | 다운로드되어 에이전트의 컨텍스트 또는 런타임 환경에 로드됩니다. | 에이전트 간 위임을 위한 작업 기능을 알립니다. |
| 사양 | 에이전트 기술 사양 | Agent2Agent (A2A) 사양 |
| 거버넌스 범위 | 개별 에이전트 배포와 독립적으로 프로젝트 전반에서 관리됩니다. | 호스트 에이전트 배포의 수명 주기에 연결됩니다. |