Neste guia, explicamos como criar, atualizar e gerenciar habilidades no registro de habilidades usando a API REST.
Antes de começar
Antes de usar o Skill Registry, configure seu ambiente:
- Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud 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 Google Cloud project.
Enable the Gemini Enterprise 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 Google Cloud 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 Google Cloud 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 email address for a Google Account.
- Click Select a role, then search for the role.
- To grant additional roles, click Add another role and add each additional role.
- Click Save.
-
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud 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 Google Cloud project.
Enable the Gemini Enterprise 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 Google Cloud 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 Google Cloud 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 email address for a Google Account.
- Click Select a role, then search for the role.
- To grant additional roles, click Add another role and add each additional role.
- Click Save.
-
Compliance
A tabela a seguir resume o status de compliance:
| Recurso | Status |
|---|---|
| Transparência no acesso | Com suporte |
| Residência de dados (DRZ) nos EUA e na UE | Com suporte |
| Chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês) | Incompatível |
| Certificação da HIPAA | Incompatível |
| VPC-SC | Incompatível |
Regiões disponíveis
O registro de habilidades está disponível nas seguintes regiões:
| Região | Local |
|---|---|
us-central1 |
Iowa |
europe-west4 |
Países Baixos |
us-east5 |
Columbus, Ohio |
Criar uma habilidade
Para criar uma nova habilidade, use o método CreateSkill. Essa operação é uma
operação de longa duração.
Para ver exemplos da estrutura de habilidade esperada, consulte os arquivos SKILL.md no
repositório de habilidades do Google Cloud.
REST
As seções a seguir descrevem como usar a API REST para criar uma habilidade.
Preparar payload
Antes de chamar a API, empacote os arquivos de habilidade em um arquivo ZIP e codifique-os em uma string base64 de linha única. Para preparar o payload, siga estas etapas:
Navegue até o diretório da habilidade:
cd <SKILL_DIRECTORY>Crie o arquivo ZIP e codifique-o em base64.
Exemplo:
zip -r skill.zip scripts/ references/ SKILL.md assets/ && base64 -w 0 -i skill.zip
Variáveis de solicitação
Antes de usar os dados da solicitação, faça as substituições a seguir:
PROJECT_ID: o ID do projeto do Google Cloud .
LOCATION: a região da sua habilidade. Para mais informações, consulte Regiões disponíveis.
SKILL_ID: o
SKILL_IDé imutável e permanece reservado permanentemente depois de criado, mesmo que você exclua a habilidade mais tarde. Os IDs de habilidade precisam obedecer às seguintes restrições:- Precisa ter de 1 a 63 caracteres.
- Só pode ter letras minúsculas, números e hífens.
- Precisa começar com uma letra e terminar com uma letra ou um número.
- Não pode começar com
gcp-(esse prefixo é reservado para habilidades integradas).
DISPLAY_NAME: o nome da habilidade usada com o agente. O método
RetrieveSkillsusa o nome de exibição e a descrição para pesquisar habilidades relevantes.DESCRIPTION: uma descrição do que a habilidade faz.
BASE64_ZIPPED_BODY: o conteúdo codificado em base64 do arquivo ZIP da habilidade.
Método HTTP e URL
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID
Corpo JSON da solicitação
{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION",
"zippedFilesystem": "BASE64_ZIPPED_BODY"
}
Comando 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
Organize os arquivos de habilidade (como SKILL.md, instruções e arquivos de código) em um
diretório local. O SDK aceita a transmissão de um caminho de diretório local (que
é compactado automaticamente) ou um caminho pré-compactado.
Para o google-cloud-aiplatform (que fornece o agentplatform) versão 1.154.0 e mais recentes:
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)
Para versões do google-cloud-aiplatform (que fornece agentplatform) anteriores à 1.154.0:
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
Organize os arquivos de habilidade (como SKILL.md, instruções e arquivos de código) em um
diretório local. O SDK aceita a transmissão de um caminho de diretório local (que
é compactado automaticamente) ou um caminho pré-compactado.
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);
Atualizar uma habilidade
Para atualizar uma habilidade, use o método UpdateSkill. Essa é uma
operação de longa duração.
É possível atualizar o nome de exibição, a descrição e o payload (sistema de arquivos compactado) de uma habilidade. Somente os campos listados no parâmetro de consulta updateMask
são atualizados.
REST
As seções a seguir descrevem como usar a API REST para atualizar uma habilidade.
Preparar payload
Opcional. Se você estiver atualizando os arquivos da habilidade, empacote os arquivos atualizados em um arquivo ZIP e codifique-os em uma string base64 de linha única:
Navegue até o diretório da habilidade:
cd <SKILL_DIRECTORY>Crie o arquivo ZIP e codifique-o em base64:
zip -r skill.zip scripts/ references/ SKILL.md assets/ && base64 -w 0 -i skill.zip
Variáveis de solicitação
Antes de usar os dados da solicitação, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto do Google Cloud .
- LOCATION: a região da habilidade. Para mais informações, consulte Regiões disponíveis.
- SKILL_ID: o ID da habilidade a ser atualizada.
- DISPLAY_NAME: opcional. Um novo nome para a habilidade.
- DESCRIPTION: opcional. Uma nova descrição do que a habilidade faz.
- BASE64_ZIPPED_BODY: opcional. O conteúdo codificado em base64 do seu arquivo ZIP atualizado da habilidade.
Método HTTP e URL
PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID
Corpo JSON da solicitação
{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION",
"zippedFilesystem": "BASE64_ZIPPED_BODY"
}
Comando curl
O comando curl a seguir atualiza o nome de exibição, a descrição e o arquivo de habilidade
compactado.
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
O SDK permite atualizar os arquivos de habilidade transmitindo um caminho de diretório local descompactado ou um caminho pré-compactado.
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
O SDK permite atualizar os arquivos de habilidade transmitindo um caminho de diretório local descompactado ou um caminho pré-compactado.
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);
Listar habilidades
Para recuperar metadados de resumo de habilidades em um local específico (incluindo o
nome, o nome de exibição e a descrição), use o método ListSkills.
REST
As seções a seguir descrevem como usar a API REST para listar habilidades.
Variáveis de solicitação
Antes de usar os dados da solicitação, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto do Google Cloud .
- LOCATION: a região das habilidades que você quer listar. Para mais informações, consulte Regiões disponíveis.
Método HTTP e URL
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills
Comando 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"
Exemplo de saída
{
"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);
}
Adquirir uma habilidade
Para recuperar os metadados e o payload da revisão mais recente de uma habilidade,
use o método GetSkill.
REST
As seções a seguir descrevem como usar a API REST para receber uma habilidade.
Variáveis de solicitação
Antes de usar os dados da solicitação, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto do Google Cloud .
- LOCATION: a região em que as habilidades estão localizadas. Para mais informações, consulte Regiões disponíveis.
- SKILL_ID: o ID da habilidade a ser recuperada.
Método HTTP e URL
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID
Comando 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);
Excluir uma habilidade
Para excluir uma habilidade e todas as revisões dela, use o método DeleteSkill.
Essa operação é uma operação de longa duração.
REST
As seções a seguir descrevem como usar a API REST para excluir uma habilidade.
Variáveis de solicitação
Antes de usar os dados da solicitação, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto do Google Cloud .
- LOCATION: a região em que a habilidade que você quer excluir está localizada. Para mais informações, consulte Regiões disponíveis.
- SKILL_ID: o ID da habilidade a ser excluída.
Método HTTP e URL
DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID
Comando 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',
});
Listar revisões de habilidades
Para recuperar o histórico de revisões de uma habilidade específica, use o método ListSkillRevisions.
REST
As seções a seguir descrevem como usar a API REST para listar revisões de habilidades.
Variáveis de solicitação
Antes de usar os dados da solicitação, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto do Google Cloud .
- LOCATION: a região em que as habilidades que você quer estão localizadas. Para mais informações, consulte Regiões disponíveis.
- SKILL_ID: o ID da habilidade.
Método HTTP e URL
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions
Comando 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"
Exemplo de saída
{
"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);
}
Receber uma revisão de habilidade
Para recuperar uma revisão específica de uma habilidade, use o método GetSkillRevision.
REST
As seções a seguir descrevem como usar a API REST para receber uma revisão de habilidade.
Variáveis de solicitação
Antes de usar os dados da solicitação, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto do Google Cloud .
- LOCATION: a região da habilidade. Para mais informações, consulte Regiões disponíveis.
- SKILL_ID: o ID da habilidade.
- REVISION_ID: o ID da revisão específica a ser recuperada. Ele
pode ser encontrado no campo
nameretornado pelo métodoListSkillRevisions. Por exemplo, se onameforprojects/1234567890/locations/us-central1/skills/cymbal-skill/revisions/4567890123, o ID da revisão será4567890123.
Método HTTP e URL
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID
Comando 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);
Recuperar habilidades
Use o método RetrieveSkills para encontrar habilidades usando a pesquisa semântica. Por
exemplo, é possível pesquisar habilidades descrevendo a tarefa que você quer
realizar, como find skills to manage cloud resources.
REST
As seções a seguir descrevem como usar a API REST para recuperar habilidades.
Variáveis de solicitação
Antes de usar os dados da solicitação, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto do Google Cloud .
- LOCATION: a região em que as habilidades que você quer pesquisar estão localizadas. Para mais informações, consulte Regiões disponíveis.
- QUERY: a string de consulta para encontrar habilidades correspondentes.
Método HTTP e URL
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills:retrieve?query=QUERY
Comando 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);
}
Acessar os detalhes de uma operação de longa duração
Alguns métodos na API Skill Registry, como CreateSkill, UpdateSkill
e DeleteSkill, são assíncronos e retornam uma operação de longa duração.
Uma operação de longa duração é um padrão de API usado para operações que podem levar um
tempo significativo para serem concluídas. Em vez de esperar que a operação seja
concluída, a API retorna um recurso de operação.
A resposta desses métodos inclui um campo name, que contém o ID da operação. Por exemplo, um name pode ser assim:
projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL_ID/operations/OPERATION_ID.
Para verificar o status e receber detalhes de uma operação de longa duração, use o
método GetOperation com o OPERATION_ID extraído.
REST
As seções a seguir descrevem como usar a API REST para receber uma operação.
Variáveis de solicitação
Antes de usar os dados da solicitação, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto do Google Cloud .
- LOCATION: a região em que a operação está em execução. Ela precisa corresponder à região usada na solicitação inicial. Para mais informações, consulte Regiões disponíveis.
- OPERATION_ID: o ID da operação. Extraia isso do campo
nameretornado porCreateSkill,UpdateSkillouDeleteSkill.
Método HTTP e URL
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID
Comando 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"
A seguir
Anexar habilidades a um agente
Saiba como anexar habilidades registradas ao criar ou atualizar um agente usando a API Managed Agents na Agent Platform.
Integração do registro de habilidades do ADK
Saiba como fazer a integração com o registro de habilidades no ADK.