Este documento explica os principais termos e conceitos relacionados ao Agent Registry.
Habilidade A2A
Compare com habilidades.
Um bloco de metadados de capacidade declarativa representado inline em um card do agente (agent-card.json). As habilidades de A2A descrevem interfaces de comunicação entre agentes e recursos de alto nível de um agente compatível com A2A.
O Agent Registry é compatível com as versões 0.3 e 1.0 da especificação Agent2Agent (A2A).
Agente
Um ator autônomo no seu ecossistema de IA, definido pelo identificador e pelas habilidades A2A ou habilidades específicas que ele possui.
Identificador do agente
Um nome globalmente exclusivo e imutável para o agente. Esse identificador lógico fornece uma referência estável para os consumidores chamarem o agente, permanecendo constante, independentemente das mudanças na infraestrutura subjacente.
Os identificadores de agente são diferentes das identidades de agente. Os identificadores de agente são URNs lógicos criados apenas para rastreamento de inventário, pesquisa de identidade entre plataformas e filtragem de serviços registrados. Já as identidades de agente representam a identidade de tempo de execução segura do agente. Para gerenciar comunicação segura e regida por políticas, use o principal do agente. Para mais informações, consulte a página Visão geral das políticas do IAM.
Os identificadores de agente são gerados automaticamente pelo Agent Registry durante a ingestão e seguem um formato de nome uniforme de recurso (URN, na sigla em inglês). O formato exato depende de onde o agente é implantado. Confira alguns exemplos:
- Ambiente de execução do agente na Gemini Enterprise Agent Platform:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:aiplatform:reasoningEngines:AGENT_ID - Serviços do Cloud Run:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:services:SERVICE_NAME - Jobs do Cloud Run:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:jobs:JOB_NAME - Implantações do GKE:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:container:clusters:CLUSTER_NAME:k8s:namespaces:NAMESPACE:apps:deployments:DEPLOYMENT_NAME - Gemini Enterprise:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:global:discoveryengine:collections:default_collection:engines:ENGINE_ID:assistants:default_assistant:agents:AGENT_ID - Google Workspace:
urn:agent:googleapis.com:locations:global:workspaceagent:workspaceagent--a2a - Agentes registrados manualmente:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:agentregistry:services:AGENT_ID
Principal do agente
O identificador exclusivo do Identity and Access Management (IAM) atribuído a um agente, permitindo que ele tenha permissões e seja auditado. Ela tem a forma de uma conta de serviçoGoogle Cloud verificável ou uma identidade de carga de trabalho gerenciada, como um ID do SPIFFE, vinculada a um agente ou servidor.
Como essa identidade está vinculada diretamente ao recurso de computação do tempo de execução do agente, a string principal incorpora o caminho exato para esse recurso subjacente. O IAM aceita três níveis de identidades de membros ao governar o acesso do agente:
- Instância de um único mecanismo: concede permissões a uma implantação
específica do agente. Por exemplo, uma instância individual do
Agent Runtime na Gemini Enterprise Agent Platform é representada por um
principal:
principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/REGION/reasoningEngines/REASONING_ENGINE_ID. - Escopo do projeto: concede permissões a todos os mecanismos de raciocínio em execução
em um projeto específico por um conjunto principal:
principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER. - Escopo em toda a organização: concede permissões a todos os agentes em toda a organização por um conjunto de principais:
principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*.
O Agent Registry mostra o principal do agente individual como um atributo somente de saída quando você visualiza os detalhes de um agente.
Para governança entre projetos, quando agentes em um projeto de carga de trabalho acessam recursos
ou roteiam o tráfego de saída por um gateway de agente central,
conceda o papel roles/iap.egressor ao principal ou conjunto de principais do agente
no recurso de destino no projeto central.
Componente agêntico
Uma entidade modular e funcional em um ecossistema de IA que o Agent Registry permite registrar, descobrir e governar. O registro categoriza os componentes agênticos em quatro tipos principais: agentes, servidores MCP, endpoints e habilidades.
Fluxo de trabalho com agentes
Uma sequência de etapas em que um agente de IA determina de forma independente o uso de ferramentas, o raciocínio e os caminhos de execução para realizar uma tarefa.
Provedor de autenticação
Uma configuração no gerenciador de autenticação de identidade do agente para armazenar, adquirir e gerenciar credenciais, como chaves de API ou tokens OAuth, para conectar seu agente a ferramentas e aplicativos externos específicos e definir o tipo de autenticação.
Vinculação
Uma conexão entre um agente de origem e um recurso de destino, como outro agente, um servidor MCP ou um endpoint. Ao criar vinculações, você estabelece relações explícitas que permitem que seus agentes orquestradores interajam com recursos downstream. As vinculações também são usadas para associar um agente a um provedor de autenticação e oferecer suporte a permissões delegadas.
Recurso de dados
Um contexto ou conjunto de dados específico exposto por um servidor MCP que um agente pode acessar para embasar as respostas ou informar as ações.
Discovery
O processo de consulta ao registro para encontrar agentes, ferramentas do MCP ou endpoints com base em descrições, tags ou habilidades.
A descoberta no Agent Registry se concentra em recursos centrados no consumo que seus orquestradores de IA podem usar. Você descobre recursos já registrados para criar e orquestrar sistemas de IA.
Esse processo no Agent Registry é diferente da descoberta de infraestrutura, como no App Hub, que identifica recursos de computação não registrados nos seus projetos do Google Cloud .
Endpoint
Para a API Agent Registry, um recurso que representa um URL de destino, geralmente uma API REST, acessado por um agente. Ao abstrair esses destinos em recursos gerenciáveis, o Agent Registry permite que você governe de forma centralizada quais serviços externos um agente pode acessar.
Protocolo de Contexto de Modelo (MCP)
O padrão aberto usado para conectar modelos de IA a fontes de dados e ferramentas, substituindo plug-ins personalizados.
Servidor MCP (ou servidor)
Um serviço que implementa o Protocolo de Contexto de Modelo (MCP) para fornecer ferramentas e recursos de dados padronizados a agentes de IA.
Identificador do servidor MCP
Um nome de recurso uniforme (URN) globalmente exclusivo e imutável para um servidor MCP. Semelhante aos identificadores de agente, esse nome fornece uma referência estável para descobrir conjuntos de ferramentas específicos.
Assim como os identificadores de agente, os identificadores de servidor MCP são nomes lógicos usados para pesquisa estável e catalogação de inventário. Para gerenciar a comunicação segura e regida por políticas, use o principal do agente.
O formato depende de ser um serviço integrado do Google ou um servidor externo registrado. Confira alguns exemplos:
- Google Cloud servidores MCP remotos:
urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:SERVER_NAME - Servidores MCP registrados manualmente:
urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:agentregistry:services:SERVER_ID
Registro
O processo de adição de um componente de agente, como um agente, servidor MCP ou endpoint, ao registro. O Agent Registry oferece os seguintes mecanismos de registro:
- Registro automático: ingestão automática de recursos de IAGoogle Cloud compatíveis, como no Agent Runtime. O registro automático opera no escopo de um único projeto.
- Registro manual: integração manual de componentes ou agentes personalizados ou externos implantados em vários Google Cloud projetos para descoberta e governança centralizadas.
URI do recurso
O local de execução física ou a infraestrutura que hospeda um agente ou um servidor MCP. O URI (Uniform Resource Identifier) é a sequência exclusiva de caracteres que identifica esse recurso de tempo de execução. Por exemplo, um URI de recurso pode ser um endpoint do tempo de execução do agente, uma implantação do Google Kubernetes Engine (GKE) ou um serviço do Cloud Run.
O URI do recurso é diferente do identificador do agente ou do identificador do servidor MCP. Esses valores são os nomes exclusivos no formato URN que identificam seus agentes e servidores MCP no registro. Já o URI do recurso aponta para o recurso de computação real em que o agente ou servidor é executado.
O caminho para o URI do recurso de um agente está incorporado à string do principal do agente para identificar exclusivamente esse recurso nas políticas do IAM. Para registros entre projetos, o URI do recurso faz referência ao projeto em que o recurso de computação reside.
O Agent Registry mostra esse URI como um atributo somente de saída quando você visualiza os detalhes de um agente.
É possível usar o URI do recurso para criar consultas no gráfico de topologia e visualizar fluxos de tráfego e relações de agentes específicos. Na API Agent Registry, esse valor é representado pelo atributo agentregistry.googleapis.com/system/RuntimeReference.
Serviço
Para a API Agent Registry, o recurso gravável usado para registrar manualmente componentes de agente personalizados ou externos no registro. Um Service representa um agente, um servidor MCP ou um endpoint adicionado manualmente ao seu registro. Você cria e gerencia um recurso Service para definir o endpoint e os metadados dos componentes de agente que o Agent Registry não ingere automaticamente.
Dependendo da especificação fornecida, o Agent Registry projeta automaticamente esse Service no lado do consumidor como um recurso Agent, McpServer ou Endpoint somente leitura para descoberta.
Você sempre usa o recurso Service para criar, editar ou excluir entradas de registro. No entanto, para receber, listar ou pesquisar essas entradas, consulte os recursos somente leitura Agent, McpServer ou Endpoint.
Habilidade
Compare com as habilidades de A2A.
Um pacote executável independente registrado como um recurso de nível superior no Agent Registry que amplia os recursos de um agente ao fornecer instruções específicas, linguagem natural ou código para concluir uma tarefa.
As habilidades contêm arquivos de instrução (SKILL.md), scripts de execução de tempo de execução e recursos de metadados.
As habilidades são identificadas por um nome uniforme de recurso (URN, na sigla em inglês). O formato exato depende do publisher. Confira alguns exemplos:
- Skills criadas pelo Google:
urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID. Por exemplo,urn:skill:discoveryengine.googleapis.com:discoveryengine:report-writing. - Habilidades registradas manualmente:
urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-SKILL_ID. Por exemplo,urn:skill:projects-123456789:locations:global:private-create-docs.
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. Você registra habilidades no Agent Registry como recursos irmãos de agentes e servidores MCP. Cada habilidade tem uma revisão padrão e pode conter várias revisões de habilidade com controle de versão.
Os administradores da plataforma governam as habilidades gerenciando os estados do ciclo de vida delas e definindo ponteiros de versão padrão para resolução de tempo de execução.
Revisão de habilidade
Um snapshot imutável e versionado de um pacote de skill. Com as revisões, é possível atualizar instruções ou código da skill sem mudar o identificador da skill principal.
Você pode gerenciar revisões de habilidades para permitir o controle de versões das suas habilidades.
Editor
Uma entidade que cria e registra habilidades no Agent Registry.
Os publishers pré-preenchidos incluem publishers do Google, como cloud.google.com e discoveryengine.googleapis.com, e parceiros verificados. As skills criadas pelo Google desses editores ficam visíveis imediatamente quando você configura o Agent Registry.
As habilidades criadas são atribuídas automaticamente ao editor private
padrão. Portanto, o ID publicado de uma habilidade específica é prefixado com
private-. Não é possível registrar recursos de editor personalizados.
Revise e inspecione os detalhes do editor das suas skills registradas.
Ferramenta
Uma função determinística fornecida por um servidor MCP que um agente pode invocar.