이 가이드에서는 REST API를 사용하여 스킬 레지스트리에서 스킬을 만들고, 업데이트하고, 관리하는 방법을 설명합니다.
시작하기 전에
스킬 레지스트리를 사용하기 전에 환경을 설정하세요.
-
In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Cloud de Confiance project.
Enable the Agent Platform API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.-
Make sure that you have the following role or roles on the project:
roles/aiplatform.viewerorroles/aiplatform.user,roles/serviceusage.serviceUsageConsumerCheck for the roles
-
In the Cloud de Confiance console, go to the IAM page.
Go to IAM - Select the project.
-
In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.
- For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.
Grant the roles
-
In the Cloud de Confiance console, go to the IAM page.
Go to IAM - Select the project.
- Click Grant access.
-
In the New principals field, enter your user identifier. This is typically the identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.
- Click Select a role, then search for the role.
- To grant additional roles, click Add another role and add each additional role.
- Click Save.
-
규정 준수
다음 표에는 규정 준수 상태가 요약되어 있습니다.
| 기능 | 상태 |
|---|---|
| 액세스 투명성 | 지원됨 |
| 미국 및 EU의 데이터 상주 (DRZ) | 지원됨 |
| 고객 관리 암호화 키(CMEK) | 지원되지 않음 |
| HIPAA 인증 | 지원되지 않음 |
| VPC-SC | 지원되지 않음 |
사용 가능한 리전
Skill Registry는 다음 지역에서 사용할 수 있습니다.
| 리전 | 위치 |
|---|---|
us-central1 |
아이오와 |
europe-west4 |
네덜란드 |
us-east5 |
오하이오 주 콜럼부스 |
기능 만들기
새 스킬을 만들려면 CreateSkill 메서드를 사용합니다. 이 작업은 장기 실행 작업입니다.
예상되는 스킬 구조의 예는 Google Cloud Skills 저장소의 SKILL.md 파일을 참고하세요.
REST
다음 섹션에서는 REST API를 사용하여 스킬을 만드는 방법을 설명합니다.
페이로드 준비
API를 호출하기 전에 스킬 파일을 zip 파일로 패키징하고 단일 행 base64 문자열로 인코딩합니다. 페이로드를 준비하려면 다음 단계를 따르세요.
스킬 디렉터리로 이동합니다.
cd <SKILL_DIRECTORY>ZIP 파일을 만들고 base64로 인코딩합니다.
예를 들면 다음과 같습니다.
zip -r skill.zip scripts/ references/ SKILL.md assets/ && base64 -w 0 -i skill.zip
요청 변수
요청 데이터를 사용하기 전에 다음을 바꿉니다.
PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
LOCATION: 스킬의 리전입니다. 자세한 내용은 사용 가능한 리전을 참고하세요.
SKILL_ID:
SKILL_ID는 변경할 수 없으며 나중에 스킬을 삭제하더라도 생성된 후에는 영구적으로 예약된 상태로 유지됩니다. 스킬 ID는 다음 제약 조건을 준수해야 합니다.- 길이는 1~63자(영문 기준)여야 합니다.
- 소문자, 숫자, 하이픈만 포함해야 합니다.
- 영문자로 시작하고 영문자나 숫자로 끝나야 합니다.
gcp-로 시작하면 안 됩니다 (이 접두사는 기본 제공 스킬용으로 예약되어 있음).
DISPLAY_NAME: 에이전트와 함께 사용되는 스킬의 이름입니다.
RetrieveSkills메서드는 표시 이름과 설명을 사용하여 관련 스킬을 검색합니다.DESCRIPTION: 스킬이 하는 일에 대한 설명입니다.
BASE64_ZIPPED_BODY: 압축된 스킬 보관 파일의 base64로 인코딩된 콘텐츠입니다.
HTTP 메서드 및 URL
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID
JSON 요청 본문
{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION",
"zippedFilesystem": "BASE64_ZIPPED_BODY"
}
curl 명령어
curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
-d '{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION",
"zippedFilesystem": "BASE64_ZIPPED_BODY"
}' \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"
Python
SKILL.md, 안내, 코드 파일과 같은 스킬 파일을 로컬 디렉터리에 정리합니다. SDK는 로컬 디렉터리 경로 (자동으로 압축됨) 또는 미리 압축된 경로를 전달하는 것을 지원합니다.
google-cloud-aiplatform (agentplatform 제공) 버전 1.154.0 이상:
import agentplatform
client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")
skill = client.skills.create(
skill_id="SKILL_ID",
display_name="DISPLAY_NAME",
description="DESCRIPTION",
config={
# Local directory path (automatically compressed) or pre-zipped path (.zip)
"local_path": "SKILL_PATH",
},
)
print(skill.name)
1.154.0보다 오래된 google-cloud-aiplatform (agentplatform 제공) 버전의 경우:
import agentplatform
client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")
skill = client.skills.create(
display_name="DISPLAY_NAME",
description="DESCRIPTION",
config={
"skill_id": "SKILL_ID",
# Local directory path (automatically compressed) or pre-zipped path (.zip)
"local_path": "SKILL_PATH",
},
)
print(skill.name)
Node.js
SKILL.md, 안내, 코드 파일과 같은 스킬 파일을 로컬 디렉터리에 정리합니다. SDK는 로컬 디렉터리 경로 (자동으로 압축됨) 또는 미리 압축된 경로를 전달하는 것을 지원합니다.
import { Client } from '@google-cloud/agentplatform';
const client = new Client({
project: 'PROJECT_ID',
location: 'LOCATION',
});
const skill = await client.skills.create({
skillId: 'SKILL_ID',
displayName: 'DISPLAY_NAME',
description: 'DESCRIPTION',
config: {
// Local directory path (automatically compressed) or pre-zipped path (.zip)
localPath: 'SKILL_PATH',
},
});
console.log(skill.name);
스킬 업데이트
기존 스킬을 업데이트하려면 UpdateSkill 메서드를 사용합니다. 이 작업은 장기 실행 작업입니다.
기존 스킬의 표시 이름, 설명, 페이로드(압축된 파일 시스템)를 업데이트할 수 있습니다. updateMask 쿼리 매개변수에 나열된 필드만 업데이트됩니다.
REST
다음 섹션에서는 REST API를 사용하여 스킬을 업데이트하는 방법을 설명합니다.
페이로드 준비
(선택사항) 스킬의 파일을 업데이트하는 경우 업데이트된 스킬 파일을 압축 파일로 패키징하고 단일 행 base64 문자열로 인코딩합니다.
스킬 디렉터리로 이동합니다.
cd <SKILL_DIRECTORY>ZIP 파일을 만들고 base64로 인코딩합니다.
zip -r skill.zip scripts/ references/ SKILL.md assets/ && base64 -w 0 -i skill.zip
요청 변수
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
- LOCATION: 스킬의 리전입니다. 자세한 내용은 사용 가능한 리전을 참고하세요.
- SKILL_ID: 업데이트할 스킬의 ID입니다.
- DISPLAY_NAME: 선택사항. 스킬의 새 이름입니다.
- DESCRIPTION: 선택사항. 스킬의 기능에 대한 새로운 설명입니다.
- BASE64_ZIPPED_BODY: 선택사항. 업데이트된 압축 스킬 보관 파일의 base64로 인코딩된 콘텐츠입니다.
HTTP 메서드 및 URL
PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID
JSON 요청 본문
{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION",
"zippedFilesystem": "BASE64_ZIPPED_BODY"
}
curl 명령어
다음 curl 명령어는 표시 이름, 설명, 압축된 스킬 파일을 업데이트합니다.
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION",
"zippedFilesystem": "BASE64_ZIPPED_BODY"
}' \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=displayName,description,zippedFilesystem"
Python
SDK는 압축 해제된 로컬 디렉터리 경로 또는 사전 압축된 경로를 전달하여 스킬 파일 업데이트를 지원합니다.
import agentplatform
client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")
skill = client.skills.update(
name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID",
config={
"display_name": "DISPLAY_NAME",
"description": "DESCRIPTION",
# Optional. Local directory path (automatically compressed) or pre-zipped path (.zip)
"local_path": "SKILL_PATH",
},
)
print(skill.name)
Node.js
SDK는 압축 해제된 로컬 디렉터리 경로 또는 사전 압축된 경로를 전달하여 스킬 파일 업데이트를 지원합니다.
import { Client } from '@google-cloud/agentplatform';
const client = new Client({
project: 'PROJECT_ID',
location: 'LOCATION',
});
const skill = await client.skills.update({
name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID',
config: {
displayName: 'DISPLAY_NAME',
description: 'DESCRIPTION',
// Optional. Local directory path (automatically compressed) or pre-zipped path (.zip)
localPath: 'SKILL_PATH',
},
});
console.log(skill.name);
기술 나열
특정 위치의 스킬에 대한 요약 메타데이터 (이름, 표시 이름, 설명 포함)를 가져오려면 ListSkills 메서드를 사용하세요.
REST
다음 섹션에서는 REST API를 사용하여 스킬을 나열하는 방법을 설명합니다.
요청 변수
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
- LOCATION: 나열할 스킬의 리전입니다. 자세한 내용은 사용 가능한 리전을 참고하세요.
HTTP 메서드 및 URL
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills
curl 명령어
curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills"
출력 예
{
"name": "projects/1234567890/locations/us-central1/skills/3456789012",
"createTime": "2026-05-10T00:02:12.497720Z",
"updateTime": "2026-05-10T00:02:19.064874Z",
"displayName": "cymbal_skill",
"description": "A skill for managing Cymbal projects.",
"state": "ACTIVE"
}
Python
import agentplatform
client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")
pager = client.skills.list()
for skill in pager:
print(skill.name, skill.display_name)
Node.js
import { Client } from '@google-cloud/agentplatform';
const client = new Client({
project: 'PROJECT_ID',
location: 'LOCATION',
});
const pager = await client.skills.list();
for await (const skill of pager) {
console.log(skill.name, skill.displayName);
}
스킬 가져오기
스킬의 최신 버전의 메타데이터와 페이로드를 가져오려면 GetSkill 메서드를 사용합니다.
REST
다음 섹션에서는 REST API를 사용하여 스킬을 가져오는 방법을 설명합니다.
요청 변수
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
- LOCATION: 스킬이 있는 리전입니다. 자세한 내용은 사용 가능한 리전을 참고하세요.
- SKILL_ID: 가져올 스킬의 ID입니다.
HTTP 메서드 및 URL
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID
curl 명령어
curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"
Python
import agentplatform
client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")
skill = client.skills.get(
name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"
)
print(skill)
Node.js
import { Client } from '@google-cloud/agentplatform';
const client = new Client({
project: 'PROJECT_ID',
location: 'LOCATION',
});
const skill = await client.skills.get({
name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID',
});
console.log(skill);
스킬 삭제
스킬과 모든 수정사항을 삭제하려면 DeleteSkill 메서드를 사용합니다.
이 작업은 장기 실행 작업입니다.
REST
다음 섹션에서는 REST API를 사용하여 스킬을 삭제하는 방법을 설명합니다.
요청 변수
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
- LOCATION: 삭제하려는 스킬이 있는 리전입니다. 자세한 내용은 사용 가능한 리전을 참고하세요.
- SKILL_ID: 삭제할 스킬의 ID입니다.
HTTP 메서드 및 URL
DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID
curl 명령어
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"
Python
import agentplatform
client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")
client.skills.delete(
name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"
)
Node.js
import { Client } from '@google-cloud/agentplatform';
const client = new Client({
project: 'PROJECT_ID',
location: 'LOCATION',
});
await client.skills.delete({
name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID',
});
스킬 버전 나열
특정 스킬의 업데이트 기록을 가져오려면 ListSkillRevisions 메서드를 사용합니다.
REST
다음 섹션에서는 REST API를 사용하여 스킬 버전을 나열하는 방법을 설명합니다.
요청 변수
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
- LOCATION: 원하는 기술이 있는 지역입니다. 자세한 내용은 사용 가능한 리전을 참고하세요.
- SKILL_ID: 스킬의 ID입니다.
HTTP 메서드 및 URL
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions
curl 명령어
curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions"
출력 예
{
"skillRevisions": [
{
"name": "projects/1234567890/locations/us-central1/skills/cymbal_skill/revisions/4567890123",
"createTime": "2026-05-10T00:02:12.497720Z",
"updateTime": "2026-05-10T00:02:19.064874Z"
}
]
}
Python
import agentplatform
client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")
response = client.skills.revisions.list(
name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"
)
for skill_revision in response.skill_revisions:
print(skill_revision.name, skill_revision.create_time)
Node.js
import { Client } from '@google-cloud/agentplatform';
const client = new Client({
project: 'PROJECT_ID',
location: 'LOCATION',
});
const response = await client.skills.revisions.list({
name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID',
});
for (const revision of response.skillRevisions || []) {
console.log(revision.name, revision.createTime);
}
스킬 버전 가져오기
스킬의 특정 버전을 가져오려면 GetSkillRevision 메서드를 사용합니다.
REST
다음 섹션에서는 REST API를 사용하여 스킬 수정 버전을 가져오는 방법을 설명합니다.
요청 변수
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
- LOCATION: 스킬의 리전입니다. 자세한 내용은 사용 가능한 리전을 참고하세요.
- SKILL_ID: 스킬의 ID입니다.
- REVISION_ID: 가져올 특정 버전의 ID입니다. 이는
ListSkillRevisions메서드에서 반환된name필드에서 확인할 수 있습니다. 예를 들어name이projects/1234567890/locations/us-central1/skills/cymbal-skill/revisions/4567890123이면 버전 ID는4567890123입니다.
HTTP 메서드 및 URL
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID
curl 명령어
curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"
Python
import agentplatform
client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")
revision = client.skills.revisions.get(
name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"
)
print(revision)
Node.js
import { Client } from '@google-cloud/agentplatform';
const client = new Client({
project: 'PROJECT_ID',
location: 'LOCATION',
});
const revision = await client.skills.revisions.get({
name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID',
});
console.log(revision);
스킬 가져오기
RetrieveSkills 메서드를 사용하여 시맨틱 검색으로 스킬을 찾습니다. 예를 들어 find skills to manage cloud resources와 같이 달성하려는 작업을 설명하여 기술을 검색할 수 있습니다.
REST
다음 섹션에서는 REST API를 사용하여 스킬을 가져오는 방법을 설명합니다.
요청 변수
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
- LOCATION: 검색하려는 기술이 있는 리전입니다. 자세한 내용은 사용 가능한 리전을 참고하세요.
- QUERY: 일치하는 스킬을 찾기 위한 쿼리 문자열입니다.
HTTP 메서드 및 URL
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills:retrieve?query=QUERY
curl 명령어
curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills:retrieve?query=QUERY"
Python
import agentplatform
client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")
response = client.skills.retrieve(
query="QUERY",
config={"top_k": TOP_K},
)
for retrieved_skill in response.retrieved_skills:
print(retrieved_skill.skill_name, retrieved_skill.description)
Node.js
import { Client } from '@google-cloud/agentplatform';
const client = new Client({
project: 'PROJECT_ID',
location: 'LOCATION',
});
const response = await client.skills.retrieve({
query: 'QUERY',
config: {
topK: TOP_K,
},
});
for (const retrievedSkill of response.retrievedSkills || []) {
console.log(retrievedSkill.skillName, retrievedSkill.description);
}
장기 실행 작업의 세부정보 가져오기
CreateSkill, UpdateSkill, DeleteSkill와 같은 Skill Registry API의 일부 메서드는 비동기적이며 장기 실행 작업을 반환합니다.
장기 실행 작업은 완료하는 데 상당한 시간이 걸릴 수 있는 작업에 사용되는 API 패턴입니다. 작업이 완료될 때까지 기다리는 대신 API는 작업 리소스를 반환합니다.
이러한 메서드의 응답에는 작업 ID가 포함된 name 필드가 포함됩니다. 예를 들어 name은 다음과 같을 수 있습니다.
projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL_ID/operations/OPERATION_ID
상태를 확인하고 장기 실행 작업의 세부정보를 가져오려면 추출된 OPERATION_ID와 함께 GetOperation 메서드를 사용합니다.
REST
다음 섹션에서는 REST API를 사용하여 작업을 가져오는 방법을 설명합니다.
요청 변수
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
- LOCATION: 작업이 실행되는 리전입니다. 이 리전은 초기 요청에 사용된 리전과 일치해야 합니다. 자세한 내용은 사용 가능한 리전을 참고하세요.
- OPERATION_ID: 작업의 ID입니다.
CreateSkill,UpdateSkill또는DeleteSkill에서 반환된name필드에서 이를 추출합니다.
HTTP 메서드 및 URL
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID
curl 명령어
curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"
다음 단계