Registrar habilidades

Visualizar

Esse produto ou recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos gerais de serviço" dos Termos específicos de serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

No Agent Registry, uma habilidade representa um recurso independente, executável que um agente pode ter. Ele contém instruções em um arquivo SKILL.md, scripts de código e recursos que estendem o raciocínio de um agente. Ao registrar habilidades independentes no Agent Registry, você pode governar, versionar e compartilhar recursos de maneira centralizada entre os agentes de IA da sua organização.

As habilidades criadas pelo Google ficam visíveis imediatamente quando você configura o Agent Registry. Este documento explica como registrar manualmente suas próprias habilidades independentes no Agent Registry.

Antes de começar

Antes de começar, configure o Agent Registry. 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 registrar habilidades no Agent Registry, peça ao administrador para conceder a você opapel 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.

Restrições de payload de ingestão

Para registrar uma habilidade, é necessário empacotar os arquivos de origem do recurso 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 está em conformidade com as seguintes restrições:

• Tamanho do arquivo ZIP:tamanho máximo do arquivo compactado de 500 KB.
• Tamanho total do payload descompactado:tamanho máximo descompactado de 10 MB.
• Tamanho do arquivo individual:tamanho máximo descompactado de 1 MB por arquivo.
• Aninhamento profundo:profundidade máxima de aninhamento de diretórios de 8 níveis.
• Conformidade com a especificação: 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 definidos na especificação de habilidades do agente.

Registrar uma habilidade

As habilidades criadas pelo Google ficam visíveis imediatamente quando você configura o Agent Registry. No entanto, também é possível registrar suas próprias habilidades manualmente. Cada habilidade tem uma revisão padrão e pode conter várias revisões versionadas de habilidade.

Para registrar suas próprias habilidades, crie um contêiner de habilidades lógicas e faça upload do payload de revisão inicial em uma única operação. Mais tarde, você poderá gerenciar as habilidades registradas e as revisões subsequentes das habilidades.

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

Por exemplo, se você criar uma habilidade com o ID workspace-tools, o nome do recurso será criado como projects/PROJECT_ID/locations/LOCATION/skills/private-workspace-tools. O nome de recurso uniforme (URN, na sigla em inglês) lógico é atribuído como urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-workspace-tools. Você precisa usar esse ID publicado (private-workspace-tools) para todas as operações de habilidades subsequentes.

Para registrar uma habilidade, siga estas etapas:

Console

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

   Acessar o Agent Registry

2. No seletor de projetos, selecione seu Google Cloud projeto.

3. Selecione a guia Habilidades.

4. Na guia Habilidades, o botão Adicionar habilidade mostra duas opções. Você pode escolher uma das seguintes opções:

   • Adicionar habilidade: cria um contêiner de habilidade no registro. Você pode fazer upload de um pacote de habilidades para criar a primeira revisão.
   • Importar habilidade: integra um novo pacote de habilidades personalizadas fazendo upload de um pacote ZIP com seu código ou arquivo de instruções de comando (SKILL.md) .

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 de habilidade empacotado 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.

     Importante: antes que o Agent Registry possa acessar seus arquivos de habilidades, você precisa conceder acesso do agente de serviço ao arquivo ZIP no seu bucket do Cloud Storage. O agente de serviço do Agent Registry usa o seguinte formato: [e-mail]. Se esse agente de serviço não existir no seu projeto, por exemplo, se você nunca criou uma habilidade, acione a criação dele para a API Agent Registry seguindo as etapas em Criar e conceder papéis a agentes de serviço. O agente de serviço exige a permissão storage.objects.get no bucket do Cloud Storage que contém o arquivo ZIP. Para instruções sobre como conceder permissões do IAM em recursos de bucket, consulte IAM para Cloud Storage.

7. Clique em Criar.

Sua habilidade foi criada. Para todas as operações de habilidades subsequentes, consulte sua habilidade como private-SKILL_ID, conforme mostrado no Google Cloud console.

gcloud

Para registrar uma habilidade e fazer upload do payload inicial, você pode fazer upload de um arquivo ZIP local ou importar um pacote armazenado no Cloud Storage.

Substitua:

• 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-. Você precisa usar o ID prefixado em todos os comandos de habilidades 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.

• 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" \
    --payload="LOCAL_ZIP_PATH"
  

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

• Importar de um bucket do Cloud Storage: para registrar uma habilidade usando um arquivo ZIP arquivado 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" \
    --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"
  

  Importante: antes que o Agent Registry possa acessar seus arquivos de habilidades, você precisa conceder acesso do agente de serviço ao arquivo ZIP no bucket do Cloud Storage. O agente de serviço do Agent Registry usa o seguinte formato: [e-mail]. Se esse agente de serviço não existir no seu projeto, por exemplo, se você nunca criou uma habilidade, acione a criação dele para a API Agent Registry seguindo as etapas em Criar e conceder papéis a agentes de serviço. O agente de serviço exige a permissão storage.objects.get no bucket do Cloud Storage que contém o arquivo ZIP. Para instruções sobre como conceder permissões do IAM em recursos de bucket, consulte IAM para Cloud Storage.

  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.

REST

Para criar uma habilidade com uma revisão inicial inline:

Método HTTP e URL

POST https://agentregistry.googleapis.com/v1alpha/projects/{project}/locations/{location}/skills?skillId={skillId}

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

Para criar uma habilidade fazendo upload de bytes de arquivo ZIP local diretamente, use o payload archiveUploadSource:

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

Substitua BASE64_ZIP_BYTES pela representação de string codificada em base64 do arquivo ZIP local.

Corpo JSON da solicitação (importar 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_ACTIVE",
  "initialRevision": {
    "gcsSource": {
      "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip"
    }
  }
}

Importante: antes que o Agent Registry possa acessar seus arquivos de habilidades, você precisa conceder acesso do agente de serviço ao arquivo ZIP no bucket do Cloud Storage. O agente de serviço do Agent Registry usa o seguinte formato: [e-mail]. Se esse agente de serviço não existir no seu projeto, por exemplo, se você nunca criou uma habilidade, acione a criação dele para a API Agent Registry seguindo as etapas em Criar e conceder papéis a agentes de serviço. O agente de serviço exige a permissão storage.objects.get no bucket do Cloud Storage que contém o arquivo ZIP. Para instruções sobre como conceder permissões do IAM em recursos de bucket, consulte IAM para Cloud Storage.

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.

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_ACTIVE",
        "initialRevision": {
          "archiveUploadSource": {
            "archiveContent": "$(base64 -w0 local_skill.zip)"
          }
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"

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

A seguir

• Saiba como gerenciar suas habilidades registradas.
• Saiba como adicionar e gerenciar revisões de habilidades.
• Analise os detalhes do editor verificado.