Concetti fondamentali

Questo documento spiega i termini e i concetti chiave relativi ad Agent Registry.

Agente

Un attore autonomo nel tuo ecosistema AI, definito dal suo identificatore e dalle competenze specifiche che possiede.

Identificatore dell'agente

Un nome univoco globale e immutabile per l'agente. Questo identificatore logico fornisce un riferimento stabile per i consumatori per chiamare l'agente, rimanendo costante indipendentemente dalle modifiche all'infrastruttura sottostante.

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:

  • Vertex AI Agent Engine: 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
  • 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 IAM univoco assegnato a un agente, che gli consente di avere autorizzazioni e di essere sottoposto a audit. Assume la forma di un account di servizio verificabile Google Cloud o di un'identità del workload gestita, ad esempio un ID SPIFFE, associata a un agente o server.

Poiché questa identità è associata direttamente alla risorsa di calcolo del runtime dell'agente, la stringa dell'entità incorpora il percorso esatto della risorsa sottostante. Ad esempio, un'entità agente per un deployment di Vertex AI Agent Engine ha il seguente aspetto:

principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/REGION/reasoningEngines/REASONING_ENGINE_ID

Agent Registry visualizza questa identità come attributo di sola uscita quando visualizzi i dettagli di un agente.

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 portare a termine 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, ad esempio 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 nel registry per trovare agenti o strumenti MCP esistenti in base a descrizioni, tag o competenze. La discovery per competenze è disponibile per gli agenti che espongono le proprie funzionalità tramite una scheda dell'agente, ad esempio quelli che implementano il protocollo Agent2Agent (A2A).

Endpoint

Per l'API Agent Registry, una risorsa che rappresenta un URL di destinazione, in genere un'API REST, a cui accede un agente. Astrattando queste destinazioni in risorse gestibili, Agent Registry ti consente di controllare a livello centrale 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 standardizzati e risorse dati agli agenti AI.

Identificatore del server MCP

Un URN (Uniform Resource Name) univoco globale e immutabile per un server MCP. Analogamente agli identificatori degli agenti, questo nome fornisce un riferimento stabile per la discovery di set di strumenti specifici.

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 al registry. Agent Registry fornisce i seguenti meccanismi di registrazione:

  • Registrazione automatica: importazione automatica dei workload supportati Google Cloud , ad esempio in Vertex AI Agent Engine.
  • Registrazione manuale: onboarding manuale di workload personalizzati o esterni.

URI risorsa

La posizione o l'infrastruttura di runtime fisica 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 Vertex AI, un deployment 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 dell'URI risorsa di un agente è incorporato nella stringa dell'entità agente principale per identificare in modo univoco il workload nei criteri IAM.

Agent Registry visualizza 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 workload 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 workload 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

Una funzionalità di alto livello posseduta da un agente A2A agente. Le competenze vengono estratte dalle schede degli agenti A2A e fungono da punti dati principali per la discovery degli agenti.

Strumento

Una funzione deterministica fornita da un server MCP che un agente può richiamare.