Modelo de dados do Agent Registry

O Agent Registry organiza seu ecossistema de IA em recursos padronizados para que você possa registrar, descobrir e governar agentes, servidores MCP, endpoints e habilidades. Entender como o Registro de Agentes separa os recursos graváveis Service dos recursos de descoberta somente leitura e quais produtos oferecem suporte ao registro automático e manual ajuda você a projetar e controlar seu registro.

Componentes agênticos

O Agent Registry permite registrar, descobrir e controlar os seguintes tipos de componentes de agentes:

  • Agentes: atores de IA autônomos que realizam tarefas específicas, invocam ferramentas e colaboram com outros agentes.
  • Servidores MCP: programas que implementam o Protocolo de Contexto de Modelo (MCP) para expor recursos e ferramentas de dados padronizados. As ferramentas são funções determinísticas expostas por um servidor MCP que os agentes podem invocar para realizar ações específicas.
  • Endpoints: URLs de destino, normalmente APIs REST, acessados por um agente. Ao abstrair esses destinos em recursos gerenciáveis, o Agent Registry permite que você controle centralmente quais APIs externas seus agentes podem acessar.
  • Habilidades: recursos modulares que ampliam o que um agente pode fazer. As habilidades independentes são pacotes de instruções e scripts opcionais controlados diretamente no registro. As habilidades de A2A são descrições de recursos no card de um agente que informam a outros agentes quando e como se comunicar com ele. Para mais informações, consulte Arquitetura de habilidades.

Recursos de serviço e recursos de descoberta

A forma como o Agent Registry representa um componente depende do tipo de componente e do modelo de registro. Para mais informações sobre ciclos de vida e descoberta de componentes, consulte Ciclo de vida e descoberta de componentes.

Agentes, servidores MCP e endpoints

Independentemente de um agente, um servidor MCP ou um endpoint ser registrado automaticamente ou manualmente, o Agent Registry o representa como um recurso de descoberta Agent, McpServer ou Endpoint somente leitura. Os consumidores, como agentes de orquestração, aplicativos cliente e desenvolvedores, usam esses recursos de descoberta para listar, pesquisar e visualizar componentes registrados.

Para componentes registrados automaticamente, o Agent Registry ingere metadados diretamente de ambientes de execução compatíveis e cria o recurso de descoberta sem um recurso Service.

Quando você registra manualmente um agente, um servidor MCP ou um endpoint, o Agent Registry separa as operações de gerenciamento da descoberta de componentes criando os seguintes itens:

  • Um recurso Service gravável: armazena os metadados do componente, incluindo o tipo de componente agêntico, o URL da interface, a descrição, a vinculação de protocolo e a especificação de capacidade. Você cria, atualiza ou exclui o recurso Service para operações de gerenciamento, como atualizar metadados ou cancelar o registro do componente, sem modificar ou excluir a implantação subjacente.
  • Um recurso de descoberta: quando você cria ou atualiza um recurso Service, o Agent Registry lê os metadados e cria ou atualiza automaticamente um recurso de descoberta Agent, McpServer ou Endpoint que representa o componente no seu registro.

As flags de especificação usadas ao criar um recurso Service determinam a coleção de recursos somente leitura resultante:

Flags Coleção de recursos Caso de uso Valores válidos
--agent-spec-type
--agent-spec-content		 Agent recurso na coleção agents Agentes REST padrão ou remotos compatíveis com A2A a2a-agent-card, no-spec
--endpoint-spec-type
--endpoint-spec-content		 Endpoint recurso na coleção endpoints URLs de serviço ou APIs REST de destino externo no-spec
--mcp-server-spec-type
--mcp-server-spec-content		 McpServer recurso na coleção mcp-servers Servidores externos do Protocolo de Contexto de Modelo (MCP) tool-spec, no-spec

Esses pares de sinalizações são mutuamente exclusivos. Especificar sinalizações de mais de um par retorna um erro. Se você especificar o par de sinalizações para o tipo de componente errado, o Agent Registry vai criar o recurso de descoberta na coleção que corresponde à sinalização especificada. Por exemplo, transmitir --agent-spec-type=no-spec ao registrar um endpoint cria um recurso Agent em vez de um recurso Endpoint. Portanto, as consultas e políticas de governança específicas do tipo não serão aplicadas conforme o esperado.

Habilidades independentes

As habilidades independentes não usam recursos Service separados. Em vez disso, você registra, cria versões e consulta habilidades diretamente usando recursos Skill de nível superior, recursos SkillRevision filhos e recursos Publisher.

Para começar, consulte Configurar o registro de agentes. Para mais informações sobre a API Agent Registry, consulte a documentação de referência da API.

Produtos e componentes compatíveis

O Agent Registry categoriza os produtos e componentes compatíveis de acordo com a forma como são registrados: automaticamente ou manualmente.

Registro automático

O Agent Registry descobre e ingere automaticamente as cargas de trabalho doGoogle Cloud compatíveis implantadas no seu projeto. Para agentes que implementam o protocolo aberto Agent2Agent (A2A), o registro extrai automaticamente as habilidades e os recursos de A2A do card de agente. As habilidades independentes gerenciadas pelo Google também podem ser descobertas em todos os projetos quando você configura o registro de agentes.

A tabela a seguir lista os produtos e componentes que o Agent Registry registra automaticamente:

Tipo de componente Produtos com suporte
Agentes
Servidores MCP
Habilidades As habilidades gerenciadas pelo Google podem ser descobertas em todos os projetos

Registro manual

Para componentes remotos, que são agentes, servidores MCP ou endpoints hospedados fora do seu projeto de governança em projetos Google Cloud separados, infraestrutura local ou nuvens externas, registre manualmente os componentes no projeto de governança usando um recurso Service. Você também usa um recurso Service para registrar manualmente componentes em ambientes de execução ou agentes não compatíveis que não implementam o protocolo A2A. Para habilidades independentes personalizadas, use um recurso Skill.

A tabela a seguir lista os produtos e componentes que você registra manualmente:

Tipo de componente Recursos suportados
Agentes Agentes remotos implantados no Compute Engine, GKE, Cloud Run, sistemas locais ou nuvens externas
Servidores MCP Componentes de agentes personalizados em ambientes de execução não compatíveis ou servidores MCP externos
Endpoints APIs REST de destino externas ou URLs de serviço controlados como endpoints
Habilidades Suas próprias habilidades independentes criadas pela sua organização

A seguir