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. Ao atualizar o código ou as instruções de uma habilidade, você cria uma nova revisão. Essa arquitetura desacoplada permite o controle de versões das suas habilidades.

Este documento explica 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 habilidades ou revisão padrão.

Antes de começar

Antes de iniciar, configure o Agent Registry e registre uma habilidade independente. Você precisa do ID do projeto para realizar estas tarefas.

Para usar os comandos da Google Cloud CLI neste documento, verifique se você configurou 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ê o papel de usuário do Agent Registry (roles/agentregistry.user) 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 com papéis personalizados ou outros papéis predefinidos.

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 habilidades atual. Quando você cria uma revisão de habilidade, ela se torna automaticamente a versão ativa da habilidade. No entanto, é possível atualizar a revisão padrão de uma habilidade a qualquer momento. Só é possível fazer o download de revisões ativas.

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

Console

  1. No Google Cloud console, acesse a página Agent Registry:

    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 o upload do pacote ou arquivo ZIP que contém seu código ou arquivo de 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 da habilidade na tabela Histórico de versões.

gcloud

É possível criar uma revisão de habilidade fazendo upload de um arquivo ZIP local ou importando 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 habilidade 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 do 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 de habilidades.

REST

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

  • Fazer upload de um arquivo ZIP local: especifique archiveUploadSource que contém 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 habilidades.
  • 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 conferir 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 habilidades ou revisão padrão.

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

Console

  1. No Google Cloud console, acesse a página Agent Registry:

    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

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

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

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

Console

  1. No Google Cloud console, acesse a página Agent Registry:

    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 de ações, clique em Fazer o download. O payload ZIP é baixado para sua máquina local.

gcloud

Para fazer o download do 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. É necessário usar a flag -L com curl para seguir 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"

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 a administradores. Não é possível excluir uma revisão definida como a revisão padrão da habilidade. Para atualizar a revisão padrão de uma habilidade, consulte Atualizar metadados de habilidades ou revisão padrão.

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

Console

  1. No Google Cloud console, acesse a página Agent Registry:

    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 de 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