Gerenciar habilidades

Depois de registrar uma habilidade independente no Agent Registry, você pode conferir os detalhes dela, atualizar a descrição, substituir o ponteiro de revisão ativa (default_revision), gerenciar os estados do ciclo de vida ou excluir do Agent Registry. Você também pode listar e ver habilidades criadas pelo Google, que ficam visíveis imediatamente quando você configura o Agent Registry.

Este documento explica como realizar essas tarefas administrativas.

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 ter as permissões necessárias para gerenciar 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, atualizar e excluir habilidades. Para mais informações, consulte Papéis e permissões do Agent Registry.

Listar e visualizar habilidades

Você pode navegar por todas as skills registradas ou pesquisar recursos específicos:

Console

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

    Acessar o Agent Registry

  2. Selecione a guia Habilidades.
  3. Revise a lista de habilidades. É possível filtrar a exibição usando os menus Localização ou Status.
  4. Clique no nome de uma habilidade para abrir a página Detalhes da habilidade, que mostra o nome, a descrição, a versão ativa, o URN da habilidade, a última atualização, os metadados personalizados e o histórico de revisões.

gcloud

Para listar todas as habilidades em um local:

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

Para ver detalhes de uma habilidade específica:

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

Substitua:

  • SKILL_ID: o ID da habilidade que você quer analisar.
  • PROJECT_ID: o ID do projeto.
  • LOCATION: o local do registro.

REST

Para recuperar a lista de todas as habilidades:

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

Para recuperar um único contêiner de habilidade:

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

Substitua:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: o local do registro.
  • SKILL_ID: o ID da habilidade que você quer analisar.

Atualizar metadados da habilidade ou revisão padrão

É possível modificar o nome de exibição, a descrição ou mudar manualmente o ponteiro de revisão padrão para implantar uma versão diferente. Para criar novas revisões de habilidade, consulte Gerenciar revisões de habilidade.

Para atualizar os metadados ou a revisão padrão de uma habilidade 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.
  3. Revise a lista de habilidades. É possível filtrar a exibição usando os menus Localização ou Status.
  4. Clique no nome de uma habilidade para abrir a página Detalhes da habilidade, que mostra o nome, a descrição, a versão ativa, o URN da habilidade, a última atualização, os metadados personalizados e o histórico de revisões.

  5. Escolha entre as seguintes opções:

    • Atualizar metadados de habilidade:

      1. Clique em Editar.
      2. No painel Editar skill, atualize o nome de exibição ou a descrição da sua skill.
      3. Clique em Salvar.

    • Atualize a revisão padrão:

      1. Localize a tabela Histórico de versões.
      2. Encontre a revisão que você quer definir como ativa.
      3. Na coluna de ações, clique em Ativar versão.

gcloud

  • Para atualizar os metadados de uma habilidade:

    gcloud alpha agent-registry skills update SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --display-name="DISPLAY_NAME" \
  --description="DESCRIPTION"

  • Para atualizar a revisão de veiculação padrão de uma habilidade:

    gcloud alpha agent-registry skills update SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --default-revision="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

Substitua:

  • SKILL_ID: o ID da habilidade que você quer atualizar.
  • PROJECT_ID: o ID do projeto.
  • LOCATION: o local do registro.
  • DISPLAY_NAME: o nome de exibição atualizado.
  • DESCRIPTION: a descrição atualizada.
  • REVISION_ID: o ID da revisão da habilidade que você quer definir como padrão.

REST

Envie uma solicitação PATCH especificando os campos que você quer atualizar:

curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "displayName": "DISPLAY_NAME",
        "description": "DESCRIPTION",
        "defaultRevision": "projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=displayName,description,defaultRevision"

Substitua:

  • DISPLAY_NAME: o nome de exibição atualizado da skill.
  • DESCRIPTION: a descrição atualizada da skill.
  • PROJECT_ID: o ID do projeto.
  • LOCATION: o local do registro.
  • SKILL_ID: o ID da habilidade que você quer atualizar.
  • REVISION_ID: o ID da revisão da habilidade que você quer ativar.

Gerenciar estados do ciclo de vida da habilidade

Para controlar como uma habilidade é resolvida durante a execução, mude o estado de destino da habilidade:

  • Rascunho:a skill está na fase inicial de criação ou desenvolvimento. Ele não é veiculado durante a execução, e os downloads de payload são bloqueados. Você pode modificar a configuração e os payloads da habilidade livremente nesse estado antes de promover a habilidade para o estado de destino Ativo.
  • Ativa:a habilidade é veiculada e totalmente resolvida.
  • Desativado:a resolução da habilidade falha imediatamente, e os downloads são bloqueados. Ao contrário do estado Desativada, é possível reativar a skill depois, o que significa retornar ao estado Ativa.
  • Descontinuado:a skill ainda pode ser carregada, mas retorna cabeçalhos de aviso indicando que será desativada.
  • Desativada:a habilidade é desativada permanentemente, não é mais veiculada e não pode ser revertida para Ativa ou qualquer outro estado. Uma habilidade só pode ser desativada depois de ter sido descontinuada. Dê tempo suficiente para migrar antes de desativar a skill. Esse é um estado terminal, recomendado para uso com extrema cautela.

Para fazer a transição do estado do ciclo de vida de uma habilidade:

Console

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

    Acessar o Agent Registry

  2. Selecione a guia Habilidades.
  3. Revise a lista de habilidades. É possível filtrar a exibição usando os menus Localização ou Status.
  4. Clique no nome de uma habilidade para abrir a página Detalhes da habilidade, que mostra o nome, a descrição, a versão ativa, o URN da habilidade, a última atualização, os metadados personalizados e o histórico de revisões.
  5. Use os botões de controle de status para fazer a transição para o estado de destino. Os botões que a página mostra dependem do estado atual da skill, por exemplo, Ativar, Desativar, Descontinuar ou Desativar.

gcloud

Atualize o contêiner de habilidade com a flag --target-state:

gcloud alpha agent-registry skills update SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --target-state=DISABLED

Os valores permitidos para o estado de destino são:

  • DRAFT
  • ACTIVE
  • DISABLED
  • DEPRECATED
  • DECOMMISSIONED.

REST

Envie uma solicitação PATCH especificando o targetState no corpo e na máscara de atualização:

curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "targetState": "TARGET_STATE_DISABLED"
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=targetState"

Os valores permitidos para o estado de destino são:

  • TARGET_STATE_DRAFT
  • TARGET_STATE_ACTIVE
  • TARGET_STATE_DISABLED
  • TARGET_STATE_DEPRECATED
  • TARGET_STATE_DECOMMISSIONED.

Excluir uma habilidade

A exclusão de um contêiner de habilidade é permanente e remove o contêiner e todo o histórico de versões imutáveis SkillRevision associado. Os agentes que tentam resolver o URN da habilidade excluída falham no tempo de execução.

Console

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

    Acessar o Agent Registry

  2. Selecione a guia Habilidades.
  3. Revise a lista de habilidades. É possível filtrar a exibição usando os menus Localização ou Status.
  4. Clique no nome da habilidade que você quer excluir.
  5. Na página Detalhes da habilidade, clique em Excluir.
  6. Na caixa de diálogo de confirmação, digite DELETE e clique em Excluir.

gcloud 

gcloud alpha agent-registry skills delete 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?force=true"

A seguir