O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Arquitetura de habilidades

No Agent Registry, as habilidades permitem empacotar instruções, scripts opcionais e conhecimento de domínio em recursos modulares que ampliam o raciocínio e o fluxo de trabalho de um agente. Ao registrar habilidades independentes no Agent Registry, é possível controlar as versões, governar e compartilhar de forma centralizada a lógica de tarefas reutilizável entre seus agentes. O Agent Registry também indexa habilidades A2A inline declaradas nos cards de agente dos seus agentes para que outros agentes possam descobri-las e invocá-las.

Tipos de habilidades

O Registro de Agentes é compatível com dois tipos de habilidades:

Habilidades independentes: pacotes com controle de versões registrados como recursos Skill de nível superior no Agent Registry. As habilidades independentes contêm arquivos de instrução SKILL.md, scripts opcionais e recursos de metadados gerenciados de forma independente de qualquer implantação de agente único.
Habilidades de A2A: descrições de recursos listadas inline no campo skills do agent-card.json card do agente que informam a outros agentes quando e como delegar trabalho a ele.

Para uma comparação entre esses dois modelos, consulte Diferenças entre as habilidades independentes e de A2A.

Habilidades independentes

As habilidades independentes são recursos de nível superior no Agent Registry, governados com agentes, servidores MCP e endpoints. Ao contrário desses componentes, as habilidades independentes não usam recursos Service separados. Em vez disso, você registra, cria versões e consulta habilidades independentes diretamente em três níveis de recursos:

Editores: recursos do Publisher que estabelecem a propriedade, o nível de verificação e a sintaxe do identificador de habilidade para uma coleção de habilidades.
Contêineres de habilidades: recursos Skill de nível superior no registro de agentes que os consumidores descobrem e resolvem no momento da execução, cada um mantendo um ponteiro para uma revisão de exibição padrão da habilidade.
Revisões de habilidades: recursos imutáveis e somente leitura do SkillRevision que contêm as instruções, os scripts opcionais e os recursos de metadados de um pacote de habilidades em uma versão específica.

Editores

Cada habilidade independente no Agent Registry pertence a um editor. Os editores estabelecem a procedência, o nível de verificação e o prefixo de nomenclatura das habilidades:

Editores gerenciados pelo Google (FIRST_PARTY): editores verificados que o Google gerencia, como cloud.google.com e discoveryengine.googleapis.com. As habilidades gerenciadas pelo Google desses editores podem ser descobertas em todos os projetos quando você configura o registro de agentes e usa o seguinte formato de identificador de habilidade: urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID. Por exemplo: urn:skill:discoveryengine.googleapis.com:discoveryengine:report-writing.
Editores particulares (PRIVATE): o editor padrão do private atribuído automaticamente a habilidades personalizadas que você registra manualmente em um projeto de governança do Google Cloud. Para evitar conflitos de nomenclatura com habilidades gerenciadas pelo Google verificadas, o Agent Registry adiciona automaticamente o prefixo private- ao identificador da habilidade. Não é possível registrar recursos personalizados do Publisher. As habilidades particulares usam o seguinte formato de nome de recurso uniforme (URN) para o identificador de habilidade: urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-SKILL_ID. Por exemplo: urn:skill:projects-PROJECT_NUMBER:locations:global:private-incident-triage.

Para instruções sobre como inspecionar editores, consulte Analisar detalhes do editor de habilidades.

Contêineres de habilidades

Um contêiner de habilidade é um recurso Skill que representa uma habilidade independente em um projeto e local de governança. Para uma habilidade criada manualmente, o Agent Registry gera um nome de recurso no formato projects/PROJECT_NUMBER/locations/LOCATION/skills/private-SKILL_ID.

O recurso Skill serve como o ponto de referência estável para descoberta no Agent Registry e mantém os seguintes campos:

Metadados descritivos: o nome de exibição legível por humanos (displayName), a descrição resumida (description), o identificador de habilidade (skillId) e a atribuição do editor.
Ponteiro de revisão padrão: o campo defaultRevision, que faz referência ao recurso SkillRevision específico disponibilizado quando os consumidores resolvem ou fazem o download da habilidade sem solicitar um ID de revisão explícito.
Estado do ciclo de vida de destino: o campo targetState, que controla se a habilidade está em um estado ativo, desativado, descontinuado ou desativado.

Para instruções sobre como visualizar e atualizar habilidades, consulte Gerenciar habilidades.

Revisões de habilidades

Um recurso de revisão de habilidade (SkillRevision) representa um snapshot imutável e com controle de versões de um pacote de habilidades. O nome do recurso está no seguinte formato: projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID.

Ao atualizar as instruções, os scripts opcionais ou os recursos de metadados de uma habilidade, você não modifica o pacote atual. Em vez disso, faça upload de um novo arquivo ZIP para criar uma nova revisão. Quando o Agent Registry valida que o arquivo atende à Especificação de habilidades do agente e às restrições de payload de ingestão, a revisão entra no estado Ativo (ACTIVE). Em seguida, é possível atualizar o ponteiro de revisão padrão na habilidade mãe para disponibilizar a nova revisão. Se você excluir a revisão definida como padrão da habilidade, o Agent Registry vai limpar o ponteiro defaultRevision e mudar o estado da habilidade ativa para Desativado (DISABLED).

Separar o contêiner de habilidade dos snapshots de revisão de habilidade oferece os seguintes benefícios:

Execução determinística: os agentes fixados em uma revisão específica são protegidos contra mudanças inesperadas de comandos ou atualizações de script.
Reversões controladas: é possível fazer upload e verificar novas revisões de habilidades ou reverter o ponteiro defaultRevision para uma revisão anterior se ocorrer um problema.
Auditabilidade: as revisões históricas do pacote de habilidades permanecem preservadas e inspecionáveis até serem explicitamente excluídas.

Para instruções sobre como fazer upload, download e excluir revisões, consulte Gerenciar revisões de habilidades.

Especificação do pacote

As habilidades independentes são empacotadas como arquivos ZIP que obedecem ao padrão aberto Especificação de habilidades de agentes.

O arquivo precisa conter um arquivo SKILL.md na raiz, além de scripts ou recursos de metadados exigidos pela habilidade. O arquivo SKILL.md define as instruções para a habilidade. Esse arquivo combina metadados de front matter YAML, como name e description, com instruções em linguagem natural interpretadas por Agent Runtimes e referências a scripts opcionais ou recursos de suporte no arquivo.

Quando você registra uma habilidade ou cria uma revisão, o Agent Registry valida o arquivo em relação às restrições de payload de ingestão, analisa o arquivo SKILL.md e indexa os metadados para pesquisa e descoberta.

Estados do ciclo de vida da habilidade

Para controlar como uma habilidade independente é resolvida e baixada no momento da execução, é possível fazer a transição do targetState do contêiner de habilidades entre quatro estados:

Ativa (ACTIVE): a habilidade é disponibilizada, indexada para descoberta e disponível para resolução de ambiente de execução e downloads de payload. Para definir uma habilidade como Ativa, o ponteiro defaultRevision precisa referenciar um recurso SkillRevision ativo.
Desativado (DISABLED): o estado inicial padrão quando uma habilidade é criada. A habilidade não é disponibilizada no ambiente de execução, e os downloads de resolução e payload falham imediatamente. Uma habilidade também passa para o estado Desativado se o ponteiro defaultRevision for limpo ou se a revisão padrão for excluída. Ao contrário do estado Desativado, é possível ativar uma habilidade desativada definindo um defaultRevision válido e atualizando o estado de destino para Ativo.
Descontinuada (DEPRECATED): a habilidade permanece resolúvel e disponível para download, mas indica aos consumidores que será desativada.
Desativado (DECOMMISSIONED): um estado final em que 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 ser descontinuada.

É possível atualizar o estado do ciclo de vida de uma habilidade usando o console do Google Cloud , a Google Cloud CLI ou a API Agent Registry sem excluir as revisões históricas. Para fazer o download do payload ZIP de uma revisão, a habilidade mãe precisa estar no estado Ativo ou Descontinuado, e a revisão precisa estar no estado Ativo. Para instruções detalhadas, consulte Gerenciar estados do ciclo de vida da habilidade.

Diferenças entre as skills independentes e as de A2A

O Agent Registry é compatível com habilidades independentes e habilidades A2A inline. A tabela a seguir compara as características deles:

Característica	Habilidade independente	Habilidade inline de A2A
Resource type	Recurso `Skill` de nível superior no Agent Registry com recursos `SkillRevision` filhos.	Matriz aninhada no recurso `Agent`.
Conteúdo do pacote	Arquivo ZIP que contém `SKILL.md`, scripts opcionais e recursos de suporte.	Objeto JSON no card do agente que contém `id`, `name` e `description`.
Modelo de controle de versões	Snapshots de revisão de habilidades imutáveis com um ponteiro `defaultRevision` configurável.	Vinculado diretamente às atualizações do `agent-card.json` do agente.
Modelo de execução	Baixados e carregados no contexto ou ambiente de execução de um agente.	Anuncia recursos de tarefas para delegação entre agentes.
Especificação	Especificação de habilidades do agente.	Especificação do Agent2Agent (A2A).
Escopo de governança	Regulamentado em todos os projetos, independentemente das implantações de agentes individuais.	Acoplado ao ciclo de vida da implantação do agente host.