Questo documento spiega i termini e i concetti chiave relativi ad Agent Registry.
Skill A2A
Confronta con le skill.
Un blocco di metadati delle funzionalità dichiarative rappresentato in linea all'interno della scheda dell'agente
Agent Card
(agent-card.json). Le skill A2A descrivono le interfacce di comunicazione da agente ad agente
e le funzionalità di alto livello possedute da un agente conforme ad A2A agent.
Agent Registry supporta le versioni 0.3 e 1.0 della specifica Agent2Agent (A2A).
Agente
Un attore autonomo nel tuo ecosistema AI, definito dal suo identificatore e dalle skill A2A o skill specifiche che possiede.
Identificatore dell'agente
Un nome univoco a livello globale e immutabile per l'agente. Questo identificatore logico fornisce un riferimento stabile per i consumer per chiamare l'agente, rimanendo costante indipendentemente dalle modifiche all'infrastruttura sottostante.
Gli identificatori degli agenti sono diversi dalle identità degli agenti. Gli identificatori degli agenti sono URN logici progettati esclusivamente per il monitoraggio dell'inventario, la ricerca dell'identità tra le superfici e il filtraggio dei servizi registrati. Al contrario, le identità degli agenti rappresentano l'identità di runtime sicura dell'agente. Per gestire la comunicazione agentica sicura e regolata dalle policy, devi utilizzare invece l' entità Agente. Per saperne di più, consulta la pagina Panoramica delle policy IAM.
Gli identificatori degli agenti vengono generati automaticamente da Agent Registry durante l'importazione e seguono un formato URN (Uniform Resource Name). Il formato esatto dipende dalla posizione in cui viene eseguito il deployment dell'agente. Di seguito sono riportati alcuni esempi:
- Agent Runtime su Gemini Enterprise Agent Platform:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:reasoningEngines:AGENT_ID - Servizi Cloud Run:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:services:SERVICE_NAME - Job Cloud Run:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:jobs:JOB_NAME - Deployment GKE:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:containers:CLUSTER_NAME:namespace:NAMESPACE:deployment:DEPLOYMENT_NAME - Gemini Enterprise:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:discoveryengine:INSTANCE_ID:root - Google Workspace:
urn:agent:googleapis.com:locations:global:workspaceagent:workspaceagent--a2a - Agenti registrati manualmente:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:agentregistry:AGENT_ID
Entità Agente
L'identificatore univoco di Identity and Access Management (IAM) assegnato a un agente, che gli consente di avere autorizzazioni ed essere sottoposto a audit. Assume la forma di un service account verificabile Google Cloud o di un'identità del workload gestita, ad esempio un ID SPIFFE, associata a un agente o a un server.
Poiché questa identità è associata direttamente alla risorsa di calcolo del runtime dell'agente, la stringa dell'entità incorpora il percorso esatto alla risorsa sottostante. IAM supporta tre livelli di identità dei membri quando regola l'accesso degli agenti:
- Singola istanza del motore: concede le autorizzazioni a un deployment specifico dell'agente. Ad esempio, una singola
istanza di Agent Runtime su Gemini Enterprise Agent Platform è rappresentata tramite un'
entità:
principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/REGION/reasoningEngines/REASONING_ENGINE_ID. - Ambito del progetto: concede le autorizzazioni a tutti i motori di ragionamento in esecuzione
all'interno di un progetto specifico tramite un set di entità:
principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER. - Ambito a livello di organizzazione: concede le autorizzazioni a tutti gli agenti dell'
intera organizzazione tramite un set di entità:
principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*.
Agent Registry mostra l'entità dell'agente individuale come attributo di sola uscita quando visualizzi i dettagli di un agente.
Per la governance tra progetti, quando gli agenti in un progetto dei workload accedono alle risorse
o instradano il traffico in uscita tramite un
Agent Gatewaycentrale,
concedi il ruolo roles/iap.egressor all'entità o al set di entità
dell'agente sulla risorsa di destinazione nel progetto centrale.
Componente agentico
Un'entità modulare e funzionale all'interno di un ecosistema AI che Agent Registry ti consente di registrare, rilevare e gestire. Il registry classifica i componenti agentici in quattro tipi principali: agenti, server MCP, endpoint e skill.
Workflow agentico
Una sequenza di passaggi in cui un agente AI determina in modo indipendente l'utilizzo degli strumenti, il ragionamento e i percorsi di esecuzione per completare un'attività.
Provider autorizzazione
Una configurazione all'interno del gestore di autenticazione di identità dell'agente per archiviare, acquisire e gestire le credenziali, come chiavi API o token OAuth, per connettere l'agente a strumenti e applicazioni esterni specifici e definire il tipo di autenticazione.
Associazione
Una connessione tra un agente di origine e una risorsa di destinazione, come un altro agente, un server MCP o un endpoint. Creando associazioni, stabilisci relazioni esplicite che consentono agli agenti orchestratori di interagire con le funzionalità downstream. Le associazioni vengono utilizzate anche per associare un agente a un provider di autenticazione per supportare le autorizzazioni delegate.
Risorsa dati
Un contesto di dati o un set di dati specifico esposto da un server MCP a cui un agente può accedere per basare le risposte o informare le sue azioni.
Discovery
Il processo di esecuzione di query sul registry per trovare agenti, strumenti MCP o endpoint esistenti in base a descrizioni, tag o skill.
La funzionalità di discovery in Agent Registry si concentra sulle funzionalità incentrate sul consumo che gli orchestratori AI possono utilizzare. Scopri le funzionalità già registrate per creare e orchestrare i sistemi AI.
Questo processo in Agent Registry è diverso dalla discovery dell'infrastruttura, ad esempio in App Hub, che identifica le risorse di calcolo non registrate nei tuoi Google Cloud progetti.
Endpoint
Per l'API Agent Registry, una risorsa che rappresenta un URL di destinazione, in genere un'API REST, a cui accede un agente. Astraggendo queste destinazioni in risorse gestibili, Agent Registry ti consente di controllare centralmente a quali servizi esterni può accedere un agente.
Model Context Protocol (MCP)
Lo standard aperto utilizzato per connettere i modelli AI a origini dati e strumenti, sostituendo i plug-in personalizzati.
Server MCP (o server)
Un servizio che implementa il Model Context Protocol (MCP) per fornire strumenti e risorse dati standardizzati agli agenti AI.
Identificatore del server MCP
Un URN (Uniform Resource Name) univoco a livello globale e immutabile per un server MCP. Analogamente agli identificatori degli agenti, questo nome fornisce un riferimento stabile per la scoperta di set di strumenti specifici.
Come gli identificatori degli agenti, gli identificatori dei server MCP sono nomi logici utilizzati per la ricerca stabile e la catalogazione dell'inventario. Per gestire la comunicazione agentica sicura e regolata dalle policy, devi utilizzare invece l'entità Agente.
Il formato dipende dal fatto che si tratti di un servizio Google integrato o di un server esterno registrato. Di seguito sono riportati alcuni esempi:
- Google Cloud Server MCP remoti:
urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:SERVER_NAME - Server MCP registrati manualmente:
urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:agentregistry:SERVER_ID
Registrazione
Il processo di aggiunta di un componente agentico, come un agente, un server MCP o un endpoint, al registry. Agent Registry fornisce i seguenti meccanismi di registrazione:
- Registrazione automatica: importazione automatica delle risorse AI supportate Google Cloud AI, ad esempio in Agent Runtime. La registrazione automatica opera nell'ambito di un singolo progetto.
- Registrazione manuale: onboarding manuale di componenti agentici personalizzati o esterni oppure di agenti di cui è stato eseguito il deployment in più Google Cloud progetti per la discovery e la governance centralizzate.
URI risorsa
La posizione di runtime fisica o l'infrastruttura che ospita un agente o server MCP. L'URI (Uniform Resource Identifier) è la sequenza univoca di caratteri che identifica questa risorsa di runtime. Ad esempio, un URI risorsa può essere un endpoint di Agent Runtime, un deployment di Google Kubernetes Engine (GKE) o un servizio Cloud Run.
L'URI risorsa è diverso dall'identificatore dell'agente o identificatore del server MCP. Questi valori sono i nomi univoci in formato URN che identificano gli agenti e i server MCP nel registry. Al contrario, l'URI risorsa punta alla risorsa di calcolo effettiva in cui viene eseguito l'agente o il server.
Il percorso all'URI risorsa di un agente è incorporato nella stringa dell'entità dell'agente per identificare in modo univoco la risorsa nelle policy IAM. Per le registrazioni tra progetti, l'URI risorsa fa riferimento al progetto in cui risiede la risorsa di calcolo.
Agent Registry mostra questo URI come attributo di sola uscita quando visualizzi i dettagli di un agente.
Puoi utilizzare l'URI risorsa per creare query nel grafico
della topologia per
visualizzare i flussi di traffico e le relazioni per agenti specifici. Nell'API Agent Registry, questo valore è rappresentato dall'attributo agentregistry.googleapis.com/system/RuntimeReference.
Servizio
Per l'API Agent Registry, la risorsa scrivibile utilizzata per registrare manualmente i componenti agentici personalizzati o
esterni nel registry. Un Service rappresenta un agente, un server MCP o un endpoint aggiunto manualmente al registry. Crea e gestisci una risorsa Service per definire l'endpoint e i metadati per i componenti agentici che Agent Registry non importa automaticamente.
A seconda della specifica fornita, Agent Registry proietta automaticamente questo Service sul lato consumer come risorsa Agent, McpServer o Endpoint di sola lettura per la discovery.
Utilizza sempre la risorsa Service per creare, modificare o eliminare le voci del registry. Tuttavia, per ottenere, elencare o cercare queste voci, esegui query sulle risorse Agent, McpServer o Endpoint di sola lettura.
Competenza
Confronta con le skill A2A.
Un pacchetto eseguibile autonomo registrato come risorsa di primo livello in
Agent Registry che estende le funzionalità di un agente fornendo istruzioni, linguaggio naturale o codice specifici per completare un'attività.
Le skill contengono file di istruzioni (SKILL.md), script di esecuzione di runtime e asset di metadati.
Le skill sono identificate da un URN (Uniform Resource Name). Il formato esatto dipende dal publisher. Di seguito sono riportati alcuni esempi:
- Skill create da Google:
urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID. Ad esempio,urn:skill:discoveryengine.googleapis.com:discoveryengine:report-writing. - Skill registrate manualmente:
urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-SKILL_ID. Ad esempio,urn:skill:projects-123456789:locations:global:private-create-docs.
Le skill create da Google sono visibili immediatamente quando configuri Agent Registry. Tuttavia, puoi anche registrare le tue skill. Registra le skill in Agent Registry come risorse di pari livello rispetto a agenti e server MCP. Ogni skill ha una revisione predefinita e può contenere più revisioni della skill con controllo delle versioni.
Gli amministratori della piattaforma gestiscono le skill gestendo i relativi stati del ciclo di vita e impostando i puntatori della versione predefinita per la risoluzione di runtime.
Revisione della skill
Uno snapshot immutabile e con controllo delle versioni di un pacchetto di skill. Le revisioni ti consentono di aggiornare le istruzioni o il codice delle skill senza modificare l'identificatore della skill principale.
Puoi gestire le revisioni delle skill per consentire il controllo delle versioni delle tue skill.
Publisher
Un'entità che crea e registra skill in Agent Registry.
I publisher precompilati includono i publisher Google, come cloud.google.com e discoveryengine.googleapis.com, e i partner verificati. Le skill create da Google da questi publisher sono visibili immediatamente quando configuri Agent Registry.
Le skill che crei vengono assegnate automaticamente al private
publisher predefinito, quindi l'ID pubblicato di una skill specifica è preceduto da
private-. Non puoi registrare risorse publisher personalizzate.
Esamina e controlla i dettagli del publisher per le skill registrate.
Strumento
Una funzione deterministica fornita da un server MCP che un agente può richiamare.