Policy estensibili su Agent Gateway

Man mano che gli agenti passano dai prototipi iniziali ai deployment aziendali, la necessità di integrare controlli interni, pipeline di dati proprietari e policy di sicurezza aziendali cresce rapidamente. A volte, le decisioni di autorizzazione complesse non possono essere espresse facilmente utilizzando solo le policy IAM standard.

Per soddisfare questi requisiti, Agent Gateway introduce un nuovo framework di policy che ti consente di supportare l'applicazione con i servizi Google, i motori di autorizzazione personalizzati o le piattaforme di sicurezza di terze parti, applicando le stesse policy universalmente ai tuoi gateway. Questo documento illustra i principali casi d'uso del rischio agentico e spiega come configurare policy estensibili.

Casi d'uso di estensibilità delle policy per i rischi degli agenti

I controlli deterministici standard sono spesso insufficienti per i workload di AI probabilistica. Le pipeline di servizi estensibili aiutano le organizzazioni a inserire una logica avanzata su misura per rischi agentici unici:

• Sanitizzazione dei contenuti e misure di sicurezza: protezione da prompt injection, jailbreak, output tossici e perdita di informazioni riservate (ad esempio, utilizzando Model Armor).
• Prevenzione della perdita di dati (DLP): monitoraggio in tempo reale dei payload e dei chunk di streaming per impedire la fuga di dati di codice proprietario o PII verso sistemi esterni.
• Governance dell'identità Zero Trust: convalida delle credenziali e applicazione dei controlli di accesso prima che un agente possa accedere a backend sensibili o strumenti esterni (ad esempio, utilizzando IAP).
• Conformità aziendale personalizzata: applicazione di regole di oscuramento dei dati personalizzate, traduzione di token o meccanismi di conformità specifici per le architetture interne.

Framework per l'estensibilità delle policy su Agent Gateway

Agent Gateway ti consente di collegare associazioni di estensioni per delegare le decisioni di autorizzazione a Policy Engine specializzati, come provider di identità, filtri di sicurezza dei contenuti o piattaforme di sicurezza di terze parti personalizzate.

Il framework di estensibilità delle policy opera su una separazione tra ruoli e risorse:

• Consumatori: operatori di Agent Gateway che vogliono aggiungere estensioni di sicurezza e governance ai propri gateway con il minimo sforzo di configurazione.

• Producer: team di piattaforme interne, servizi Google proprietari (come IAP e Model Armor) e partner ISV di terze parti che creano e pubblicano estensioni dei servizi per l'utilizzo da parte di altri.

• ExtensionBinding: una risorsa creata dal consumer che associa un ProducerExtension a un Agent Gateway di destinazione, insieme alle condizioni di corrispondenza che determinano quando viene richiamata l'estensione. Questa è l'unica risorsa che un consumer deve creare per iniziare a utilizzare un'estensione.

• ProducerExtension: una risorsa creata dal producer che pacchettizza un motore di autorizzazione compatibile con ext_proc in un'unica unità gestita. Incapsula tutti i parametri di esecuzione e le impostazioni di connettività sottostanti, in modo che i consumer non debbano configurare i meccanismi del piano dati di basso livello.

Estensioni proprietarie di Google integrate

I servizi Google proprietari (1P), come IAP e Model Armor, offrono funzionalità di estensione predefinite con un modello operativo semplificato.

• Consumer: gli sviluppatori di applicazioni e gli operatori delle operazioni di sicurezza agiscono come consumer. Per attivare l'autenticazione zero-trust o la protezione dal prompt injection, crea una risorsa ExtensionBinding che ha come target gli URI degli endpoint di servizio predefiniti di Google direttamente dal tuo progetto consumer.
• Produttore: Google agisce in qualità di produttore. Google crea, ospita e gestisce l'infrastruttura di servizi e gli endpoint di estensione sottostanti a livello globale (ad esempio iap.googleapis.com o modelarmor.us.rep.googleapis.com). Non è necessario creare o gestire una risorsa ProducerExtension.

Estensioni aziendali e di partner (2P/3P)

Per la Custom Governance, l'estensibilità delle policy consente un modello di integrazione flessibile su due lati tra i team aziendali e i partner di sicurezza.

• Producer: i team interni di platform engineering (2P) o i fornitori di sicurezza ISV di terze parti (3P) agiscono come producer. Il producer crea un servizio gRPC compatibile con il protocollo ext_proc di Envoy, lo ospita in un progetto producer dedicato (ad esempio un servizio Cloud Run dietro un bilanciatore del carico delle applicazioni), lo espone utilizzando un collegamento al servizio Private Service Connect (PSC) e pubblica una risorsa ProducerExtension.

• Consumer: gli sviluppatori di applicazioni e gli amministratori della sicurezza dei progetti consumer agiscono come consumer. Una volta concesso l'accesso utilizzando PSC dal producer, i consumer creano un ExtensionBinding nel proprio progetto che fa riferimento all'URI della risorsa ProducerExtension specifico per applicare controlli personalizzati (come le norme di governance semantica o le regole firewall di terze parti) ai propri workload.

Pattern di deployment

Le associazioni di estensioni supportano pattern di deployment flessibili per applicare una governance coerente in tutti i percorsi di traffico, in modo che le policy di governance agiscano in modo identico, indipendentemente da dove vengono eseguiti i deployment degli agenti. L'API ExtensionBinding si applica in modo uniforme a tutti i modelli di deployment di Agent Gateway.

Percorsi di intercettazione del traffico end-to-end

Puoi applicare le associazioni di estensioni per intercettare il traffico nei seguenti percorsi di comunicazione all'interno del tuo ecosistema di agenti:

• Utente → Agente (Ingress): intercetta le richieste in entrata da utenti finali o applicazioni client destinate ad Agent Gateway per applicare l'autenticazione utente, la governance dell'identità o la sanitizzazione del prompt injection.
• Agente → Strumento / MCP (traffico in uscita): intercetta le chiamate in uscita dagli agenti ai server Model Context Protocol (MCP) o alle API esterne per convalidare le autorizzazioni e sanitizzare gli input degli strumenti.
• Agente → Modello LLM (traffico in uscita): analizza i prompt prima che raggiungano i foundation model e filtra le risposte del modello per prevenire la perdita di dati o output tossici.

• Agent → Agent (A2A Egress): controlla la comunicazione tra agenti e applica i limiti delle policy quando gli agenti autonomi collaborano tra progetti.

Da client ad agente

Da agente a ovunque

Consumer: associa le estensioni agli Agent Gateway

I consumer (come gli sviluppatori di applicazioni o gli operatori di sicurezza) collegano la logica di governance e sicurezza ai propri Agent Gateway creando un ExtensionBinding. Questa risorsa associa il workload di destinazione a un'estensione e dichiara le condizioni di corrispondenza per definire esattamente quando richiamare l'estensione (ad esempio, intercettando il traffico diretto a strumenti esterni o server MCP specifici). Puoi specificare le condizioni di corrispondenza direttamente in linea (come mostrato negli esempi di questa sezione) o in un file YAML separato.

A seconda del provider di estensioni, l'utilizzo segue uno dei due percorsi:

Configurazione consumer 1P

Per i servizi Google come IAP (IAP) o Model Armor, Google gestisce l'infrastruttura di backend e la registrazione a livello globale. In qualità di consumer, non è necessario scegliere come target un URI della risorsa ProducerExtension specifico. Puoi associare direttamente questi servizi ai tuoi workload passando le stringhe degli endpoint predefiniti (ad es. iap.googleapis.com o modelarmor.us.rep.googleapis.com) come target in ExtensionBinding.

Associa un'estensione IAP a un Agent Gateway

L'esempio seguente mostra una risorsa ExtensionBinding che associa un servizio Google proprietario (IAP) a un Agent Gateway in un progetto consumer. In base al campo matchConditions specificato, questa estensione viene richiamata quando il traffico viene inviato a un server MCP.

1. Crea un file YAML con la seguente configurazione:

   name: EXTENSION_BINDING_NAME
   target:
     resources:
     - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
   matchConditions:
   - to:
       destination:
         resources:
         - prefix: "urn:mcp"
   producerExtension: "iap.googleapis.com"
   

   Sostituisci quanto segue:

   • EXTENSION_BINDING_NAME: il nome della risorsa di associazione dell'estensione.
   • PROJECT_ID: il tuo ID progetto Cloud de Confiance by S3NS .
   • LOCATION: la località del gateway e dell'associazione dell'estensione.
   • AGENT_GATEWAY_NAME: il nome dell'Agent Gateway di destinazione.

2. Importa la configurazione dell'associazione dell'estensione:

   gcloud beta service-extensions extension-bindings import EXTENSION_BINDING_NAME \
    --location=LOCATION \
    --source=EXTENSION_BINDING_FILE_PATH

   Sostituisci EXTENSION_BINDING_FILE_PATH con il percorso del file di configurazione YAML.

Associa un'estensione Model Armor a un Agent Gateway

Per proteggere gli agenti da prompt injection, contenuti tossici e fughe di dati sensibili, puoi associare Model Armor direttamente al tuo workload. In base al campo matchConditions specificato, questa estensione viene richiamata quando il traffico viene inviato a un server MCP.

1. Crea un file YAML con la seguente configurazione:

   name: EXTENSION_BINDING_NAME
   target:
     resources:
     - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
   matchConditions:
   - to:
       destination:
         resources:
         - prefix: "urn:mcp"
   producerExtension: "modelarmor.us.rep.googleapis.com"
   failOpen: true
   producerMetadata:
     model_armor_settings: '[{
       "request_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID",
       "response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID"
     }]'
   

   Sostituisci quanto segue:

   • EXTENSION_BINDING_NAME: il nome della risorsa di associazione dell'estensione.
   • PROJECT_ID: il tuo ID progetto Cloud de Confiance .
   • LOCATION: la località delle risorse.
   • AGENT_GATEWAY_NAME: il nome dell'Agent Gateway di destinazione.
   • TEMPLATE_PROJECT_ID: l'ID progetto in cui si trovano i template di Model Armor.
   • REQUEST_TEMPLATE_ID: l'ID del template Model Armor utilizzato per valutare le richieste.
   • RESPONSE_TEMPLATE_ID: l'ID del template Model Armor utilizzato per valutare le risposte.

2. Importa la configurazione dell'associazione dell'estensione:

   gcloud beta service-extensions extension-bindings import EXTENSION_BINDING_NAME \
    --location=LOCATION \
    --source=EXTENSION_BINDING_FILE_PATH

   Sostituisci EXTENSION_BINDING_FILE_PATH con il percorso del file di configurazione YAML.

Configurazione consumer 2P/3P

In qualità di consumer di un'estensione dei servizi creata da un altro team interno (2P) o da un fornitore di terze parti esterno (3P), è tua responsabilità assicurarti che al tuo progetto consumer sia stato concesso esplicitamente l'accesso per utilizzare il servizio. L'accesso è controllato dal producer utilizzando la configurazione del collegamento al servizio Private Service Connect. Una volta ottenuto l'accesso, associa il workload facendo riferimento all'URI della risorsa ProducerExtension specifico fornito dal producer nel tuo ExtensionBinding.

Associa motori di autorizzazione personalizzati

L'esempio seguente mostra una risorsa ExtensionBinding che associa un'estensione personalizzata di un progetto producer di terze parti o di Google a un Agent Gateway in un progetto consumer. In base al campo matchConditions specificato, questa estensione viene richiamata quando il traffico viene inviato a un agente.

1. Crea un file YAML con la seguente configurazione:

   name: EXTENSION_BINDING_NAME
   target:
     resources:
     - "projects/CONSUMER_PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
   matchConditions:
   - to:
       destination:
         resources:
         - prefix: "urn:agent"
   producerExtension: "projects/PRODUCER_PROJECT_ID/locations/LOCATION/producerExtensions/PRODUCER_EXTENSION_NAME"
   

   Sostituisci quanto segue:

   • EXTENSION_BINDING_NAME: il nome della risorsa di associazione dell'estensione.
   • CONSUMER_PROJECT_ID: l'ID progetto del progetto consumer che ospita l'Agent Gateway.
   • LOCATION: la località delle risorse.
   • AGENT_GATEWAY_NAME: il nome dell'Agent Gateway di destinazione.
   • PRODUCER_PROJECT_ID: l'ID progetto del progetto producer che ospita ProducerExtension.
   • PRODUCER_EXTENSION_NAME: il nome della risorsa ProducerExtension.

2. Importa la configurazione dell'associazione dell'estensione:

   gcloud beta service-extensions extension-bindings import EXTENSION_BINDING_NAME \
    --location=LOCATION \
    --source=EXTENSION_BINDING_FILE_PATH

   Sostituisci EXTENSION_BINDING_FILE_PATH con il percorso del file di configurazione YAML.

Punti di collegamento dell'associazione dell'estensione

Le associazioni delle estensioni possono essere configurate a diversi livelli della gerarchia delle risorse, a seconda dei requisiti di governance:

• Livello Agent Gateway: collega le policy direttamente a una risorsa Agent Gateway per gestire tutto il traffico che passa attraverso il gateway.
• Livello di progetto: crea ExtensionBindings che si applicano a livello globale a tutte le risorse di un determinato tipo all'interno di un progetto, semplificando la gestione per gli amministratori aziendali che applicano la conformità a livello di progetto.

Associa un'estensione Model Armor a tutti gli Agent Gateway di un progetto

1. Crea un file YAML con la seguente configurazione:

   name: EXTENSION_BINDING_NAME
   target:
     scope:
       parent: "projects/PROJECT_NUMBER"
       resourceTypes: "AGENT_GATEWAY"
   matchConditions:
   - to:
       destination:
         resources:
         - prefix: "urn:mcp"
   producerExtension: "modelarmor.us.rep.googleapis.com"
   failOpen: true
   producerMetadata:
     model_armor_settings: '[{
       "request_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID",
       "response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID"
     }]'
   

   Sostituisci quanto segue:

   • EXTENSION_BINDING_NAME: il nome della risorsa di associazione dell'estensione.
   • PROJECT_NUMBER: il numero del tuo progettoCloud de Confiance .
   • TEMPLATE_PROJECT_ID: l'ID progetto in cui si trovano i template di Model Armor.
   • LOCATION: la località delle risorse.
   • REQUEST_TEMPLATE_ID: l'ID del template Model Armor utilizzato per valutare le richieste.
   • RESPONSE_TEMPLATE_ID: l'ID del template Model Armor utilizzato per valutare le risposte.

2. Importa la configurazione dell'associazione dell'estensione:

   gcloud beta service-extensions extension-bindings import EXTENSION_BINDING_NAME \
    --location=LOCATION \
    --source=EXTENSION_BINDING_FILE_PATH

   Sostituisci EXTENSION_BINDING_FILE_PATH con il percorso del file di configurazione YAML.

Per le richieste corrispondenti a un workload specifico, vengono eseguiti sia i binding delle estensioni a livello di progetto sia quelli a livello di risorsa. Se la stessa estensione è configurata sia a livello di risorsa che di progetto, verrà richiamata due volte.

Condizioni di corrispondenza per richiamare le estensioni

Le condizioni di corrispondenza determinano quando viene richiamata l'estensione. Puoi specificare le condizioni di corrispondenza direttamente in linea (come mostrato negli esempi precedenti in questa pagina) o in un file YAML.

Questa sezione fornisce esempi di configurazioni di file YAML per situazioni comuni basate sul flusso di traffico, sugli URN delle risorse di destinazione o sugli host di destinazione:

• Traffico in uscita verso i server degli strumenti MCP (agente → strumento): intercetta il traffico inviato da un agente ai server degli strumenti Model Context Protocol (MCP) remoti:

  # Invoke extension for all agent traffic to remote MCP servers
  - to:
      destination:
        resources:
        - prefix: "urn:mcp"
  

• Traffico in entrata (utente → agente): intercetta le richieste in entrata da utenti finali o applicazioni client destinate agli agenti regolati da Agent Gateway (ad esempio, per applicare l'autenticazione dell'utente finale o la sanitizzazione del prompt injection in entrata):

  # Invoke extension on incoming user requests targeting agents
  - to:
      destination:
        resources:
        - prefix: "urn:agent"
  

• In uscita verso i modelli LLM (agente → modello LLM): intercetta le richieste inviate dagli agenti ai modelli LLM di base o ai server di modelli in base alla corrispondenza con l'host di destinazione:

  # Invoke extension on traffic sent to a specific model server
  - to:
      destination:
        hosts:
        - exact: "myexamplemodelserver.com"
  

Producer: crea e pubblica estensioni

In qualità di producer personalizzato (2P o 3P), ospita l'implementazione dell'estensione dei servizi basata su ext_proc dietro un collegamento Private Service Connect. Una volta pronto l'allegato, crea una risorsa ProducerExtension specificando la fase di elaborazione della richiesta in cui opera l'estensione, l'autorità da utilizzare e l'URI dell'allegato PSC per il servizio ext_proc:

gcloud beta service-extensions producer-extensions create PRODUCER_EXTENSION_NAME \
  --phase authz \
  --extension-settings=service=projects/PRODUCER_PROJECT_ID/regions/REGION/serviceAttachments/PSC_ATTACHMENT_NAME,authority="example.provider.net"

Sostituisci quanto segue:

• PRODUCER_EXTENSION_NAME: il nome della risorsa ProducerExtension.
• PRODUCER_PROJECT_ID: l'ID progetto del progetto producer.
• REGION: la regione del collegamento del servizio Private Service Connect.
• PSC_ATTACHMENT_NAME: il nome del collegamento al servizio Private Service Connect.

Ospita estensioni personalizzate su Cloud Run

Per i producer che vogliono eseguire il proprio servizio gRPC ext_proc personalizzato senza gestire cluster o VM dedicati, Cloud Run è un'alternativa serverless ideale.

Per pubblicare l'estensione serverless come ProducerExtension, esponila utilizzando Private Service Connect (PSC). Poiché le risorse ProducerExtension richiedono un URI del collegamento al servizio PSC e i collegamenti ai servizi hanno come target le regole di forwarding del bilanciatore del carico anziché i servizi Cloud Run direttamente, posiziona un bilanciatore del carico delle applicazioni (utilizzando un backend NEG serverless) davanti al servizio Cloud Run.

Ecco il flusso di lavoro di deployment generale per l'hosting dell'estensione su Cloud Run:

1. Esegui il deployment dell'estensione su Cloud Run: ospita la tua estensione gRPC ext_proc personalizzata come servizio containerizzato su Cloud Run.

2. Crea un NEG serverless:esegui il deployment di un gruppo di endpoint di rete (NEG) serverless che punta all'estensione in esecuzione su Cloud Run.

3. Configura un bilanciatore del carico con il backend NEG serverless: configura un bilanciatore del carico delle applicazioni regionale all'interno della tua rete VPC, con il NEG serverless come backend.

4. Pubblica il servizio con PSC:crea un collegamento al servizio Private Service Connect che punta direttamente alla regola di forwarding del bilanciatore del carico. In questo modo viene generato un URI del collegamento al servizio univoco (ad esempio, projects/.../regions/.../serviceAttachments/...).

5. Crea l'estensione Producer: utilizza questo URI generato per creare un'istanza della risorsa ProducerExtension.

6. Associa i workload dei consumer: i consumer ora possono associare i propri gateway alla tua estensione facendo riferimento all'URI della risorsa ProducerExtension.

Appendice: metadati contestuali per le estensioni personalizzate

Per aiutare le estensioni personalizzate a prendere decisioni di autorizzazione ed elaborazione sensibili al contesto,i piani dati Cloud de Confiance passano il ciclo di vita e il contesto delle risorse direttamente ai serverext_proc.

Queste informazioni vengono raggruppate come metadati non tipizzati all'interno del campo metadata_context di ext_proc gRPC ProcessingRequest. Questi metadati si trovano nello spazio dei nomi com.google.serviceextensions.invocation_info e utilizzano il formato google.protobuf.Struct standard.

Puoi decodificare o convertire questi metadati in JSON per l'elaborazione downstream. Di seguito è riportato un esempio di formato JSON per una richiesta che ha come target un Agent Gateway con traffico indirizzato a un server MCP:

{
 "binding_selector" : {
   "target" : "//networkservices.googleapis.com/projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME",
   "project_number" : PROJECT_NUMBER,
   "to_resource": "urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:SERVER_ID"
 }
}

Lo schema del file JSON è il seguente:

message ServiceExtensionsInvocationInfo {
  message ExtensionBindingSelector {
    // The target (gateway ID, etc) in fully qualified name format.
    // For example:
    // "//networkservices.googleapis.com/projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
    string target = 1;
    // Project number associated with the target.
    uint64 project_number = 2;
    // The destination resource within the Agent Registry that traffic is directed to.
    string to_resource = 3;
  }
  ExtensionBindingSelector binding_selector = 1;
}