Registrar habilidades

O Agent Registry permite empacotar e registrar manualmente habilidades independentes. As habilidades independentes agrupam instruções do agente com recursos de metadados associados e scripts opcionais para ampliar o raciocínio e o fluxo de trabalho de um agente. Ao registrar suas próprias habilidades independentes no Agent Registry, é possível controlar, criar versões e compartilhar recursos reutilizáveis de forma centralizada, além das habilidades gerenciadas pelo Google que estão disponíveis ao configurar o Agent Registry.

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. 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 registrar habilidades no Registro de Agentes, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto de governança em que o Registro de Agentes 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 Registro de Agentes também podem incluir as permissões necessárias para registrar e gerenciar habilidades e revisões de habilidades. Para mais informações, consulte Papéis e permissões do Agent Registry.

Restrições de payload de ingestão

Para registrar uma habilidade, é preciso empacotar os arquivos de origem dela em um arquivo ZIP. O arquivo precisa incluir um arquivo de instrução SKILL.md na raiz. Durante a fase de ingestão do processo de registro de habilidades, o Agent Registry valida se o payload obedece às seguintes restrições:

  • Tamanho do arquivo ZIP: tamanho máximo de 500 KB.
  • Tamanho total do payload descompactado: tamanho máximo descompactado de 10 MB.
  • Tamanho do arquivo individual: tamanho máximo não compactado de 1 MB por arquivo.
  • Aninhamento profundo: profundidade máxima de aninhamento de diretórios de 8 níveis.
  • Conformidade com as especificações: o arquivo SKILL.md precisa conter uma seção de front matter YAML válida que defina o nome, a descrição e os metadados, conforme definido na Especificação de habilidades do agente.

Registrar uma habilidade

É possível registrar manualmente suas próprias habilidades no Agent Registry. Para informações sobre preços e custos de recursos para habilidades, consulte Preços do Agent Registry.

Para registrar suas habilidades, faça o seguinte:

Console

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

    Acessar o Agent Registry

  2. No seletor de projetos, selecione o projeto do Google Cloud .

  3. Selecione a guia Habilidades.

  4. Na guia Habilidades, o botão Adicionar habilidade mostra duas opções para criar um contêiner de habilidades e importar o pacote inicial de habilidades. Escolha uma das seguintes opções:

    • Adicionar habilidade: cria um contêiner de habilidade no registro. Se quiser, você pode fazer upload de um pacote de habilidades para criar a primeira revisão.
    • Importar habilidade: registre um novo pacote de habilidades personalizadas fazendo upload de um pacote ZIP com o arquivo de instruções SKILL.md e scripts opcionais.

  5. No painel Criar habilidade ou Importar habilidade, especifique os seguintes detalhes:

    • Nome de exibição: insira um nome fácil de usar para a habilidade.
    • Descrição: insira um breve resumo explicando os recursos da habilidade.
    • Local: selecione a região geográfica, por exemplo, global, us ou eu.

  6. Na seção Origem do payload, escolha uma das seguintes opções:

    • Arquivo: arraste o arquivo ZIP da habilidade empacotada ou navegue pelo diretório local.

    • Bucket: insira o caminho para o arquivo ZIP armazenado em um bucket do Cloud Storage, no formato gs://BUCKET_NAME/SKILL_PACKAGE.zip.

  7. Clique em Criar.

    Sua habilidade é criada no estado Desativado (DISABLED). Para todas as operações de habilidade subsequentes, consulte sua habilidade como private-SKILL_ID, conforme exibido no console doGoogle Cloud .

  8. Para disponibilizar a habilidade para descoberta de agentes, defina a revisão padrão e atualize o estado de destino para Ativo. Para ver instruções, consulte Gerenciar estados do ciclo de vida da habilidade.

gcloud

  1. Crie o contêiner de habilidade e faça upload do payload de revisão inicial com o comando gcloud alpha agent-registry skills create. É possível fazer upload de um arquivo ZIP local ou importar um pacote armazenado no Cloud Storage:

    • Fazer upload de um arquivo ZIP local: para registrar uma habilidade usando um payload ZIP local:

      gcloud alpha agent-registry skills create SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --target-state=disabled \
    --payload="LOCAL_ZIP_PATH"

      Substitua LOCAL_ZIP_PATH pelo caminho para o arquivo de habilidade empacotado na máquina local, por exemplo, ./workspace-docs-skill.zip.

    • Importar de um bucket do Cloud Storage: para registrar uma habilidade usando um arquivo ZIP hospedado em um bucket do Cloud Storage:

      gcloud alpha agent-registry skills create SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --target-state=disabled \
    --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 o payload de habilidades.

    Substitua o seguinte em qualquer um dos comandos:

    • SKILL_ID: o ID do recurso da habilidade, por exemplo, workspace-docs-skill. Após a criação, o registro adiciona automaticamente o prefixo private-. Use o ID com prefixo em todos os comandos de habilidade subsequentes, por exemplo, private-workspace-docs-skill.
    • PROJECT_ID: o ID do projeto;
    • LOCATION: a região geográfica, por exemplo, global, us ou eu.
    • DISPLAY_NAME: um nome fácil de usar para a habilidade.
    • DESCRIPTION: um breve resumo explicando os recursos da habilidade.

  2. As habilidades recém-criadas começam no estado Desativado (DISABLED). Para disponibilizar a habilidade para descoberta de agentes, defina a revisão padrão e atualize o estado de destino para Ativo. Para ver instruções, consulte Gerenciar estados do ciclo de vida da habilidade.

REST

  1. Crie o contêiner de habilidade com uma revisão inicial inline:

    Método HTTP e URL

    POST https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID

    Substitua:

    • PROJECT_ID: o ID do projeto;
    • LOCATION: o local do registro.
    • SKILL_ID: um identificador exclusivo para o contêiner de habilidade.

    Corpo JSON da solicitação (upload de arquivo local)

    Para criar uma habilidade fazendo upload direto de bytes de arquivo ZIP local, use o payload archiveUploadSource. Durante a criação, targetState precisa ser definido como TARGET_STATE_DISABLED:

    {
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "type": "SIMPLE",
  "targetState": "TARGET_STATE_DISABLED",
  "initialRevision": {
    "archiveUploadSource": {
      "archiveContent": "BASE64_ZIP_BYTES"
    }
  }
}

    Substitua:

    • DISPLAY_NAME: um nome fácil de usar para a habilidade.
    • DESCRIPTION: um breve resumo explicando os recursos da habilidade.
    • BASE64_ZIP_BYTES: a representação de string codificada em base64 do arquivo ZIP local.

    Corpo JSON da solicitação (importação do Cloud Storage)

    Como alternativa, para criar uma habilidade usando um arquivo armazenado em um bucket do Cloud Storage, use gcsSource:

    {
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "type": "SIMPLE",
  "targetState": "TARGET_STATE_DISABLED",
  "initialRevision": {
    "gcsSource": {
      "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip"
    }
  }
}

    Substitua:

    • DISPLAY_NAME: um nome fácil de usar para a habilidade.
    • DESCRIPTION: um breve resumo explicando os recursos da habilidade.
    • 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 o payload da habilidade.

    Comando curl (upload de arquivo local)

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "type": "SIMPLE",
      "targetState": "TARGET_STATE_DISABLED",
      "initialRevision": {
        "archiveUploadSource": {
          "archiveContent": "'"$(base64 -w0 local_skill.zip)"'"
        }
      }
    }' \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"

    Substitua:

    • DISPLAY_NAME: um nome fácil de usar para a habilidade.
    • DESCRIPTION: um breve resumo explicando os recursos da habilidade.
    • PROJECT_ID: o ID do projeto;
    • LOCATION: o local do registro.
    • SKILL_ID: um identificador exclusivo para o contêiner de habilidade.

    Para fazer upload de um arquivo de bucket do Cloud Storage, substitua o corpo JSON da solicitação pelos campos e valores correspondentes.

  2. As habilidades recém-criadas começam no estado Desativado (DISABLED). Para disponibilizar a habilidade para descoberta de agentes, defina a revisão padrão e atualize o estado de destino para Ativo. Para ver instruções, consulte Gerenciar estados do ciclo de vida da habilidade.

As habilidades que você ou outros usuários criam são atribuídas automaticamente ao editor padrão private para evitar conflitos de nome com as habilidades gerenciadas pelo Google. Por esse motivo, o ID do publisher de uma habilidade específica se torna private-SKILL_ID. Não é possível especificar um editor personalizado durante a criação da habilidade.

Por exemplo, se você criar uma habilidade com o ID workspace-tools, o nome do recurso será criado como projects/PROJECT_NUMBER/locations/LOCATION/skills/private-workspace-tools. O identificador de habilidade é atribuído como urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-workspace-tools. Use o ID do publisher private-workspace-tools para todas as operações de habilidade subsequentes.

A seguir