Gerenciar revisões de habilidades

No Agent Registry, uma revisão de habilidade representa um snapshot imutável e versionado de um pacote de habilidades. Quando você atualiza o código ou as instruções de uma skill, cria uma nova revisão. Essa arquitetura desacoplada permite o controle de versões das suas habilidades.

Neste documento, explicamos como criar e gerenciar revisões de habilidades. Para informações sobre como atualizar a revisão padrão de uma habilidade específica, consulte Atualizar metadados de habilidade ou revisão padrão.

Antes de começar

Antes de começar, configure o Agent Registry e registre uma habilidade independente. Você precisa do ID do projeto para realizar essas tarefas.

Para usar os comandos da Google Cloud CLI neste documento, verifique se você configurou seu ambiente da CLI gcloud.

Funções exigidas

Para receber as permissões necessárias para gerenciar revisões de habilidades no Registro de agentes, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

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, fazer o download, 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

Ao criar uma revisão, um novo payload ZIP é enviado para o contêiner de habilidade atual. Quando você cria uma revisão de skill, ela se torna automaticamente a versão ativa da skill. No entanto, você pode atualizar a revisão padrão de uma habilidade a qualquer momento. Somente revisões ativas 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 skill é de 500 KB.

Console

  1. No console 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 do arquivo ZIP que contém seu código ou instruções de comando (SKILL.md). 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 na tabela Histórico de versões.

gcloud

Para criar uma revisão de skill, 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 da habilidade.
  • SKILL_ID: o ID da habilidade que você está usando para a revisão.
  • PROJECT_ID: o ID do projeto.

  • LOCATION: o local do registro.

  • Fazer upload de um arquivo ZIP local: para criar uma revisão de skill usando um payload ZIP local:

    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:

    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 da 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. É possível usar o comando base64 inline 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.
  • REVISION_ID: o ID que você quer atribuir a esta 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 conferir a lista de todas as revisões de uma skill e inspecionar os metadados delas. Se você quiser atualizar a revisão padrão de uma habilidade, consulte Atualizar metadados da habilidade ou revisão padrão.

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

Console

  1. No console 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 da 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:

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:

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

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"

Fazer o download do payload de revisão

Você pode baixar o payload do arquivo ZIP compilado de uma revisão específica para verificação ou depuração local.

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

Para fazer o download da carga útil de uma revisão ativa, siga estas etapas:

Console

  1. No console 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 o download. O payload ZIP é baixado para sua máquina local.

gcloud

Para baixar o payload do arquivo de uma revisão, execute o comando describe com a flag --alt=media e redirecione a saída para um arquivo:

gcloud alpha agent-registry skills revisions describe REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --flags="alt=media" > skill_payload.zip

REST

Envie uma solicitação GET para o URL do recurso da revisão, adicionando o parâmetro de consulta alt=media. Use a flag -L com curl para seguir fluxos 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"

Excluir uma revisão específica

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

A exclusão de revisões individuais geralmente é restrita aos administradores. Não é possível excluir uma revisão definida como a revisão padrão da skill. Para atualizar a revisão padrão de uma habilidade, consulte Atualizar metadados da habilidade ou revisão padrão.

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

Console

  1. No console 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 

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

REST 

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"

A seguir