Registrar habilidades

Visualizar

Este produto ou recurso está sujeito aos "Termos das Soluções 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 uma capacidade independente e executável que um agente pode ter. Ele contém instruções em um arquivo SKILL.md, scripts de código e recursos que ampliam o raciocínio de um agente. Ao registrar habilidades independentes no Agent Registry, você pode governar, controlar versões 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. Neste documento, explicamos como registrar manualmente suas próprias habilidades autônomas no Registro de agentes.

Antes de começar

Antes de começar, configure o Agent Registry. 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 registrar habilidades no Agent Registry, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

• Registrar e gerenciar habilidades independentes: Usuário do Agent Registry (roles/agentregistry.user)
• Registre e gerencie habilidades independentes e outros recursos do Agent Registry: Editor da API Agent Registry (roles/agentregistry.editor)

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 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, você precisa empacotar os arquivos de origem da capacidade em um arquivo ZIP. O arquivo precisa incluir um arquivo de instruções SKILL.md na raiz. Durante a fase de ingestão do processo de registro de habilidades, o Registro de agentes 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:máximo 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 oito 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 definido 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, você também pode registrar suas próprias habilidades manualmente. Cada habilidade tem uma revisão padrão e pode conter várias revisões de habilidade com controle de versão.

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

Para informações sobre preços e custos de recursos para habilidades, consulte Preços do Agent Registry.

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

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 uniforme de recurso (URN) lógico é atribuído como urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-workspace-tools. Use esse ID publicado (private-workspace-tools) para todas as operações de skill subsequentes.

Para registrar uma habilidade, siga estas etapas:

Console

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

   Acessar o Agent Registry

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

3. Selecione a guia Habilidades.

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

   • Adicionar habilidade: crie um contêiner de habilidade no registro. Você pode fazer upload de um pacote de skill para criar a primeira revisão.
   • Importar habilidade: integre 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 as funcionalidades da habilidade.
   • Local: selecione a região geográfica, por exemplo, global, us ou eu.

6. Na seção Origem da carga útil, escolha uma das seguintes opções:

   • Arquivo:arraste o arquivo ZIP da skill empacotada ou procure no 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 os arquivos de habilidade, você precisa conceder ao agente de serviço acesso 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 tiver criado 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 precisa da permissão storage.objects.get no bucket do Cloud Storage que contém seu arquivo ZIP. Para instruções sobre concessão de 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 habilidade subsequentes, consulte sua habilidade como private-SKILL_ID, conforme exibido no consoleGoogle Cloud .

gcloud

Para registrar uma skill e fazer upload da carga inicial, envie um arquivo ZIP local ou importe um pacote armazenado no Cloud Storage.

Substitua:

• SKILL_ID: o ID do recurso da habilidade, por exemplo, workspace-docs-skill. Depois da criação, o registro adiciona automaticamente o prefixo private-. Você precisa usar 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 as capacidades da skill.

• 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 habilidade empacotado na sua máquina local, por exemplo, ./workspace-docs-skill.zip.

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

  Importante: antes que o Agent Registry possa acessar seus arquivos de habilidade, você precisa conceder ao agente de serviço acesso 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 tiver criado 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 precisa da permissão storage.objects.get no bucket do Cloud Storage que contém seu arquivo ZIP. Para instruções sobre concessão de 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 a carga útil da habilidade.

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 enviando bytes de um 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 seu 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_ACTIVE",
  "initialRevision": {
    "gcsSource": {
      "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip"
    }
  }
}

Importante: antes que o Agent Registry possa acessar seus arquivos de habilidade, você precisa conceder ao agente de serviço acesso 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 tiver criado 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 precisa da permissão storage.objects.get no bucket do Cloud Storage que contém seu arquivo ZIP. Para instruções sobre concessão de 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 a carga útil 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_ACTIVE",
        "initialRevision": {
          "archiveUploadSource": {
            "archiveContent": "$(base64 -w0 local_skill.zip)"
          }
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"

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

A seguir

• Saiba como gerenciar suas skills registradas.
• Saiba como adicionar e gerenciar revisões de habilidades.
• Revise os detalhes do publisher verificado.