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 em um único projeto ou em um limite de gerenciamento. Entender como o Registro de Agentes separa os recursos graváveis Service dos recursos de descoberta somente leitura, define o escopo dos recursos entre projetos e oferece 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.

Modelo de dados entre projetos

Quando você configura um limite de gerenciamento, o Registro de Agente centraliza a descoberta e a governança em todos os projetos membros do seu projeto de gerenciamento.

Ao consultar, listar ou pesquisar recursos do projeto de gerenciamento, o Agent Registry aplica as seguintes regras de escopo para fornecer um catálogo consolidado sem duplicar recursos ou criar colisões de endpoints:

Categoria do recurso Escopo em um limite de gerenciamento Descrição
Recursos descobertos automaticamente Agregado de projetos de membros Os agentes e servidores MCP descobertos automaticamente nos projetos membros são agregados à visualização do projeto de gerenciamento quando você os lista ou pesquisa em um local no projeto de gerenciamento. Ao visualizar, listar ou pesquisar um agente ou servidor MCP, especifique o ID do projeto de gerenciamento ou o ID do projeto de membro na solicitação. O nome do recurso preserva o ID que o Agent Registry atribui ao componente e usa o projeto especificado na solicitação.
Recursos registrados manualmente Com escopo para o projeto em que são criados Os agentes personalizados, os servidores MCP externos e os endpoints registrados manualmente como recursos Service têm como escopo o projeto em que são criados. Crie-os no projeto de gerenciamento para que fiquem visíveis em todo o limite de gerenciamento ou em um projeto membro para que fiquem visíveis apenas nesse projeto.
Vinculações Com escopo para o projeto em que são criados Os recursos do Binding têm como escopo o projeto em que são criados. Crie-os no projeto de gerenciamento para visibilidade em todo o limite ou em um projeto membro para visibilidade de projeto único.
Skills e publishers independentes Com escopo para o projeto em que são criados Os recursos personalizados independentes Skill, SkillRevision e Publisher têm como escopo o projeto em que são criados e não são agregados de projetos membros para o projeto de gerenciamento. As habilidades independentes gerenciadas pelo Google podem ser descobertas em todos os projetos automaticamente quando você configura o Registro de Agentes.
Aplicativos de IA Com escopo para o projeto em que são criados Os recursos AiApplication somente leitura e as visualizações de componentes vinculadas têm como escopo o projeto e o local em que o aplicativo foi criado.

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 ou em projetos membros no seu limite de gerenciamento. Para agentes que implementam o protocolo aberto Agent2Agent (A2A), o registro extrai automaticamente as habilidades e os recursos de A2A do card do 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

Os componentes remotos são agentes, servidores MCP ou endpoints hospedados fora do seu projeto de governança ou limite de gerenciamento, como em projetos do Google Cloud separados sem um limite, infraestrutura local ou nuvens externas. Registre manualmente esses componentes remotos 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 não compatíveis ou para agentes 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