Criar e gerenciar habilidades

Este guia explica como criar, atualizar e gerenciar habilidades no Skill Registry usando a API REST.

Antes de começar

Antes de usar o Skill Registry, configure seu ambiente:

  1. 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 the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. 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.

    Enable the API

  4. Make sure that you have the following role or roles on the project: roles/aiplatform.viewer or roles/aiplatform.user, roles/serviceusage.serviceUsageConsumer

    Check for the roles

    1. In the Cloud de Confiance console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. 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.

    4. 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

    1. In the Cloud de Confiance console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. 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.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. 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) 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 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, coloque os arquivos da sua skill em um arquivo zipado e codifique-o em uma string base64 de uma única linha. Para preparar a carga útil, siga estas etapas:

  1. Navegue até o diretório de habilidades:

    cd <SKILL_DIRECTORY>

  2. 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 Cloud de Confiance by S3NS .

  • 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 após a criação, mesmo que você exclua a skill depois. 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 skills integradas.

  • DISPLAY_NAME: o nome da habilidade usada com o agente. O método RetrieveSkills usa o nome de exibição e a descrição para pesquisar habilidades relevantes.

  • DESCRIPTION: uma descrição do que a skill faz.

  • BASE64_ZIPPED_BODY: o conteúdo codificado em base64 do arquivo zipado da sua skill.

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 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 a 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 operação é uma operação de longa duração.

É possível atualizar o nome de exibição, a descrição e a carga útil (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 skill, coloque os arquivos atualizados em um arquivo zipado e codifique-o em uma string base64 de linha única:

  1. Navegue até o diretório de habilidades:

    cd <SKILL_DIRECTORY>

  2. 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 Cloud de Confiance by S3NS .
  • 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 arquivo zipado atualizado da sua skill.

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 Cloud de Confiance by S3NS .
  • 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 a carga útil 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 Cloud de Confiance by S3NS .
  • 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 é 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 Cloud de Confiance by S3NS .
  • 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 habilidade

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 Cloud de Confiance by S3NS .
  • LOCATION: a região em que as habilidades desejadas 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 Cloud de Confiance by S3NS .
  • 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. Isso pode ser encontrado no campo name retornado pelo método ListSkillRevisions. Por exemplo, se o name for projects/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, você pode pesquisar habilidades descrevendo a tarefa que 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 Cloud de Confiance by S3NS .
  • 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 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 termine, 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 ter esta aparência: 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 Cloud de Confiance by S3NS .
  • LOCATION: a região em que a operação está sendo executada. 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 name retornado por CreateSkill, UpdateSkill ou DeleteSkill.

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

Guia

Saiba como anexar habilidades registradas ao criar ou atualizar um agente usando a API Agentes Gerenciados na Agent Platform.

Guia

Saiba como fazer a integração com o Skill Registry no ADK.