Gerenciar revisões de habilidades

No Agent Registry, as revisões de habilidades permitem controlar as versões das suas habilidades independentes como snapshots imutáveis sem interromper os agentes ativos. Cada habilidade tem uma revisão padrão e pode conter várias revisões de habilidade com controle de versões. Ao atualizar as instruções ou os scripts opcionais de uma habilidade, é possível criar, listar, inspecionar, baixar e excluir revisões de habilidades no Agent Registry. Para informações sobre como atualizar a revisão padrão de uma habilidade, consulte Atualizar metadados de habilidade ou revisão padrão.

Antes de começar

  1. Configure o Agent Registry.

  2. Consiga o ID do projeto para o projeto de governança em que o Agent Registry está ativado.

  3. Registrar uma habilidade independente.

  4. Para usar os comandos da Google Cloud CLI neste documento, configure o ambiente da CLI gcloud.

Funções exigidas

Para receber as permissões necessárias para gerenciar revisões de habilidades no Agent Registry, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto de governança em que o Agent Registry está ativado:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Outros papéis do Agent Registry também podem incluir as permissões necessárias para visualizar, baixar, criar, atualizar e excluir revisões de habilidades. Para mais informações, consulte Papéis e permissões do Agent Registry.

Criar uma revisão de habilidade

A criação de uma nova revisão faz o upload de um novo payload ZIP para o contêiner de habilidade atual. Quando a validação é bem-sucedida, a revisão entra no estado Ativo. Para disponibilizar a nova revisão como padrão para a habilidade, atualize a revisão padrão da habilidade para apontar para a nova revisão ativa. Somente as revisões no estado Ativo podem ser baixadas.

Para informações sobre preços e custos de recursos para habilidades, consulte Preços do Agent Registry.

O tamanho máximo do arquivo ZIP de uma revisão de habilidade é de 500 KB.

Console

  1. No console do Google Cloud , acesse a página Registro de agentes:

    Acessar o Agent Registry

  2. Selecione a guia Habilidades e clique no nome da sua habilidade.
  3. Na página Detalhes da habilidade, localize a tabela Histórico de versões.
  4. Clique em Adicionar versão.

  5. No painel Adicionar versão, escolha uma das seguintes opções:

    • Arquivo: faça upload do pacote ou arquivo ZIP que contém o arquivo de instruções SKILL.md e os scripts opcionais. Clique em Procurar para encontrar o arquivo no ambiente local.

    • Bucket: forneça um URI do Cloud Storage gs://... que contenha um pacote ZIP válido. Clique em Procurar para encontrar o arquivo nos buckets do Cloud Storage.

  6. Clique em Criar.

A página Detalhes da habilidade mostra a revisão da habilidade na tabela Histórico de versões.

gcloud

Para criar uma revisão de habilidade, faça upload de um arquivo ZIP local ou importe um pacote armazenado no Cloud Storage.

Substitua:

  • REVISION_ID: o ID que você quer atribuir à revisão de habilidade.
  • SKILL_ID: o ID da habilidade que você está usando para a revisão. Para habilidades registradas manualmente, inclua o prefixo private-, como private-my-skill.
  • PROJECT_ID: o ID do projeto;

  • LOCATION: o local do registro.

  • Fazer upload de um arquivo ZIP local: para criar uma revisão de habilidade usando um payload ZIP local, execute o comando gcloud alpha agent-registry skills revisions create:

    gcloud alpha agent-registry skills revisions create REVISION_ID \
    --skill=SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --payload="LOCAL_ZIP_PATH"

    Substitua LOCAL_ZIP_PATH pelo caminho para o arquivo de habilidade empacotado na sua máquina local.

  • Importar de um bucket do Cloud Storage: para criar uma revisão de habilidade usando um arquivo ZIP hospedado em um bucket do Cloud Storage, execute o comando gcloud alpha agent-registry skills revisions create:

    gcloud alpha agent-registry skills revisions create REVISION_ID \
    --skill=SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"

    Substitua:

    • BUCKET_NAME: o nome do bucket do Cloud Storage que contém o pacote ZIP.
    • SKILL_PACKAGE: o nome do pacote de habilidades que contém a revisão de habilidade.

REST

Para criar uma revisão de habilidade, envie uma solicitação POST para a coleção de revisões. É possível fazer upload do payload ZIP diretamente ou apontar para um caminho do Cloud Storage.

  • Fazer upload de um arquivo ZIP local: especifique archiveUploadSource contendo os bytes ZIP codificados em base64 no corpo da solicitação. Use o comando inline base64 em curl:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
        "archiveUploadSource": {
          "archiveContent": "'"$(base64 -w0 local_skill.zip)"'"
        }
      }' \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions?skillRevisionId=REVISION_ID"

  • Importar de um bucket do Cloud Storage: especifique gcsSource no corpo da solicitação apontando para o caminho do bucket:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
        "gcsSource": {
          "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip"
        }
      }' \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions?skillRevisionId=REVISION_ID"

Substitua:

  • PROJECT_ID: o ID do projeto;
  • LOCATION: o local do registro.
  • SKILL_ID: o ID do contêiner de habilidade. Para habilidades registradas manualmente, inclua o prefixo private-, como private-my-skill.
  • REVISION_ID: o ID que você quer atribuir a essa revisão.
  • BUCKET_NAME: o nome do bucket do Cloud Storage que contém o ZIP.
  • SKILL_PACKAGE: o nome do pacote ZIP.

Listar e descrever revisões

É possível ver a lista de todas as revisões de uma habilidade e inspecionar os metadados delas. Se você quiser atualizar a revisão padrão de uma habilidade, consulte Atualizar metadados de habilidade ou revisão padrão.

Para listar e ver detalhes de uma revisão, siga estas etapas:

Console

  1. No console do Google Cloud , acesse a página Registro de agentes:

    Acessar o Agent Registry

  2. Selecione a guia Habilidades e clique no nome da sua habilidade.
  3. Na página Detalhes da habilidade, localize a tabela Histórico de versões.
  4. Revise os IDs de versão, o horário de criação, o estado da revisão e as ações disponíveis.

gcloud

Para listar todas as revisões de uma habilidade, execute o comando gcloud alpha agent-registry skills revisions list:

gcloud alpha agent-registry skills revisions list \
    --skill=SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION

Para descrever os metadados de uma revisão específica, execute o comando gcloud alpha agent-registry skills revisions describe:

gcloud alpha agent-registry skills revisions describe REVISION_ID \
    --skill=SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION

Substitua:

  • SKILL_ID: o ID do contêiner de habilidade. Para habilidades registradas manualmente, inclua o prefixo private-, como private-my-skill.
  • PROJECT_ID: o ID do projeto;
  • LOCATION: o local do registro.
  • REVISION_ID: o ID da revisão da habilidade.

REST

Para listar revisões:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions"

Para receber metadados de uma única revisão:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

Substitua:

  • PROJECT_ID: o ID do projeto;
  • LOCATION: o local do registro.
  • SKILL_ID: o ID do contêiner de habilidade. Para habilidades registradas manualmente, inclua o prefixo private-, como private-my-skill.
  • REVISION_ID: o ID da revisão da habilidade.

Fazer o download do payload de revisão

É possível fazer o download do payload do arquivo ZIP de uma revisão específica para verificação local ou depuração.

Para baixar o payload, as duas condições a seguir precisam ser atendidas:

Para fazer o download do payload de uma revisão ativa, siga estas etapas:

Console

  1. No console do Google Cloud , acesse a página Registro de agentes:

    Acessar o Agent Registry

  2. Selecione a guia Habilidades e clique no nome da sua habilidade.
  3. Na página Detalhes da habilidade, localize a tabela Histórico de versões.
  4. Encontre a revisão que você quer baixar.
  5. Na coluna Ações, clique em Fazer download. O payload ZIP é salvo na máquina local.

gcloud

Para fazer o download do payload de arquivo de uma revisão, execute o comando gcloud alpha agent-registry skills revisions download e especifique o caminho de destino:

gcloud alpha agent-registry skills revisions download REVISION_ID \
    --skill=SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --destination="./skill_payload.zip"

Substitua:

  • REVISION_ID: o ID da revisão da habilidade que será baixada.
  • SKILL_ID: o ID do contêiner de habilidade. Para habilidades registradas manualmente, inclua o prefixo private-, como private-my-skill.
  • PROJECT_ID: o ID do projeto;
  • LOCATION: o local do registro.

REST

Envie uma solicitação GET ao URL do recurso da revisão adicionando o parâmetro de consulta alt=media. Use a sinalização -L com curl para seguir os streams de redirecionamento HTTP:

curl -L -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -o skill_payload.zip \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID?alt=media"

Substitua:

  • PROJECT_ID: o ID do projeto;
  • LOCATION: o local do registro.
  • SKILL_ID: o ID do contêiner de habilidade. Para habilidades registradas manualmente, inclua o prefixo private-, como private-my-skill.
  • REVISION_ID: o ID da revisão da habilidade que será baixada.

Excluir uma revisão específica

A exclusão de uma revisão específica remove o payload ZIP e o histórico de metadados do Agent Registry.

A exclusão de revisões individuais geralmente é restrita aos administradores. Se você excluir a revisão definida como padrão da habilidade, o Agent Registry vai limpar o ponteiro defaultRevision e mudar uma habilidade Ativa para o estado Desativada. Para manter a habilidade ativa, atualize a revisão padrão da habilidade para que ela aponte para outra revisão ativa antes de excluir a revisão padrão anterior.

Para excluir uma revisão específica, siga estas etapas:

Console

  1. No console do Google Cloud , acesse a página Registro de agentes:

    Acessar o Agent Registry

  2. Selecione a guia Habilidades e clique no nome da sua habilidade.
  3. Na página Detalhes da habilidade, localize a tabela Histórico de versões.
  4. Encontre a revisão que você quer excluir.
  5. Na coluna Ações, clique em Excluir e confirme a ação.

gcloud

Para excluir uma revisão, execute o comando gcloud alpha agent-registry skills revisions delete:

gcloud alpha agent-registry skills revisions delete REVISION_ID \
    --skill=SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION

Substitua:

  • REVISION_ID: o ID da revisão de habilidade a ser excluída.
  • SKILL_ID: o ID do contêiner de habilidade. Para habilidades registradas manualmente, inclua o prefixo private-, como private-my-skill.
  • PROJECT_ID: o ID do projeto;
  • LOCATION: o local do registro.

REST

Para excluir uma revisão, envie uma solicitação DELETE:

curl -X DELETE \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

Substitua:

  • PROJECT_ID: o ID do projeto;
  • LOCATION: o local do registro.
  • SKILL_ID: o ID do contêiner de habilidade. Para habilidades registradas manualmente, inclua o prefixo private-, como private-my-skill.
  • REVISION_ID: o ID da revisão de habilidade a ser excluída.

A seguir