Gestisci gli agenti con Agent Gateway

Agent Gateway ti consente di gestire il traffico in uscita dagli agenti AI che crei e ospiti su Cloud Run. Se instradi il traffico in uscita dal tuo servizio Cloud Run attraverso un Agent Gateway autogestito in esecuzione su Secure Web Proxy, puoi applicare policy di accesso centralizzate, ispezionare i payload per la sicurezza dei contenuti e raccogliere dati di telemetria di osservabilità nei tuoi workload agentici.

Questo documento descrive come configurare un'architettura centralizzata per Agent Gateway su Cloud Run e spiega come:

Architettura

In un deployment autogestito centralizzato, Secure Web Proxy funge da punto di applicazione delle policy ed è eseguito all'interno della rete Virtual Private Cloud (VPC). Il container sidecar di Ambient Networking intercetta il traffico in uscita dall'agente Cloud Run e lo instrada tramite il traffico VPC diretto in uscita alla tua istanza di Secure Web Proxy. Secure Web Proxy applica le regole di accesso e dei contenuti dai punti di decisione relativa alle norme, come Identity-Aware Proxy (IAP) e Model Armor.

Diagramma dell'architettura che mostra un servizio Cloud Run con un container agente e un container proxy sidecar ambientale che instrada il traffico tramite il traffico VPC diretto in uscita a un Agent Gateway autogestito supportato da Secure Web Proxy all'interno di una rete VPC.
Figura 1. Architettura Agent Gateway autogestito per un agente Cloud Run.

Per instradare e gestire il traffico in questa architettura, configura i seguenti componenti:

  • Traffico in uscita VPC diretto e Ambient Networking: il tuo servizio Cloud Run si connette alla rete VPC con --vpc-egress=all e --ambient-networking, che utilizza l'ambito regionale per impostazione predefinita e instrada tutto il traffico in uscita alla rete VPC.
  • Agent Gateway autogestito: una risorsa Agent Gateway logica in modalità autogestita punta all'istanza Secure Web Proxy nella tua rete VPC.
  • Policy di routing in uscita: una policy EgressRouting dell'API Network Services indirizza il traffico in uscita dal servizio Cloud Run all'istanza Secure Web Proxy.

Prima di iniziare

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Install the Google Cloud CLI.

  5. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Install the Google Cloud CLI.

  10. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init

  12. Abilita l'API Cloud Run Admin, l'API Network Services, l'API Network Security, l'API Service Extensions, l'API Model Armor, l'API Certificate Authority Service, l'API Certificate Manager, l'API Cloud Resource Manager, l'API App Hub, l'API Identity and Access Management, l'API Identity-Aware Proxy, l'API Compute Engine, l'API Traffic Director, l'API Cloud DNS, l'API Network Connectivity e l'API Agent Registry, se non sono già abilitate.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilita le API

  13. Crea una rete VPC e una subnet con l'accesso privato Google abilitato sulla subnet.
  14. Configura Agent Registry nel tuo progetto o nella tua organizzazione.
  15. Installa e inizializza Google Cloud CLI.
  16. Aggiorna i componenti di gcloud CLI: 
    gcloud components update

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per configurare Agent Gateway per Cloud Run, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Se configuri un deployment tra progetti con VPC condiviso, chiedi all'amministratore di concederti il ruolo roles/compute.xpnAdmin a livello di organizzazione o cartella.

Crea un Agent Gateway autogestito

Prima di creare la risorsa Agent Gateway, esegui il deployment e configura un'istanza di Secure Web Proxy nella tua rete VPC, come descritto in Esegui il deployment di Secure Web Proxy come Agent Gateway:

  1. Configura l'ispezione TLS e crea una policy di sicurezza del gateway che colleghi il tuo TlsInspectionPolicy. Non hai bisogno di regole delle policy di sicurezza o di elenchi di URL di Secure Web Proxy.
  2. Crea una risorsa ServerTlsPolicy con allowOpen: false e mtlsPolicy.clientValidationMode: ALLOW_INVALID_OR_MISSING_CLIENT_CERT. Non impostare clientValidationTrustConfig.
  3. Esegui il deployment di un'istanza Secure Web Proxy in modalità di routing del proxy esplicito con addresses, ports, certificateUrls, gatewaySecurityPolicy e serverTlsPolicy configurati quando crei il gateway in modo che Cloud Run passi la Workload Identity dell'agente a Secure Web Proxy e IAP su mTLS.

Una volta pronta l'istanza di Secure Web Proxy, crea una risorsa Agent Gateway autogestita che punti all'istanza di Secure Web Proxy:

  1. Crea un file di configurazione YAML denominato my-agent-gateway.yaml:

    name: AGENT_GATEWAY_NAME
registries:
  - "//agentregistry.googleapis.com/projects/PROJECT_ID/locations/REGION"
selfManaged:
  resourceUris:
    - "projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME"

    Sostituisci quanto segue:

    • AGENT_GATEWAY_NAME: il nome che vuoi assegnare alla risorsa Agent Gateway.
    • PROJECT_ID: l'ID progetto che ospita l'istanza di Secure Web Proxy.
    • REGION: la regione dell'istanza di Secure Web Proxy, ad esempio us-central1.
    • SWP_NAME: il nome dell'istanza Secure Web Proxy.

  2. Importa la configurazione di Agent Gateway:

    gcloud beta network-services agent-gateways import AGENT_GATEWAY_NAME \
   --source="my-agent-gateway.yaml" \
   --location=REGION \
   --project=PROJECT_ID

  3. Verifica la risorsa Agent Gateway:

    gcloud beta network-services agent-gateways describe AGENT_GATEWAY_NAME \
   --location=REGION \
   --project=PROJECT_ID

    Prima di procedere alla sezione successiva, verifica che l'output mostri la configurazione di selfManaged e l'URI della risorsa dell'istanza di Secure Web Proxy.

Configura il networking Ambient di Cloud Run per accedere all'API Traffic Director

Quando configuri un servizio Cloud Run con il traffico VPC diretto in uscita e --vpc-egress=all, tutte le connessioni in uscita dall'istanza del container vengono instradate attraverso la rete VPC. Ciò include la connessione del sidecar Envoy a trafficdirector.REGION.rep.googleapis.com.

Per consentire al sidecar di risolvere e raggiungere l'API Traffic Director, configura una zona Cloud DNS privata nella tua rete VPC in base all'utilizzo o meno dei Controlli di servizio VPC nel tuo ambiente:

Senza Controlli di servizio VPC

Se il tuo progetto non utilizza i Controlli di servizio VPC, crea una zona DNS privata di Cloud DNS che instrada le richieste di trafficdirector.REGION.rep.googleapis.com all'indirizzo IP del gateway di Secure Web Proxy in modo che Secure Web Proxy consenta il traffico:

  1. Recupera l'indirizzo IP interno del gateway Secure Web Proxy:

    SWP_IP=$(gcloud network-services gateways describe SWP_NAME \
 --project="PROJECT_ID" \
 --location="REGION" \
 --format="value(addresses[0])")

    Sostituisci quanto segue:

    • SWP_NAME: il nome dell'istanza Secure Web Proxy.
    • PROJECT_ID: il tuo ID progetto Google Cloud .
    • REGION: la regione del deployment.

  2. Crea una zona Cloud DNS gestita privata per l'API Traffic Director:

    gcloud dns managed-zones create td-swp-zone \
 --project="PROJECT_ID" \
 --dns-name="trafficdirector.REGION.rep.googleapis.com." \
 --description="Private DNS zone routing control plane traffic to SWP" \
 --visibility="private" \
 --networks="VPC_NETWORK_NAME"

    Sostituisci VPC_NETWORK_NAME con il nome della tua rete VPC.

  3. Aggiungi un record A che punti il dominio regionale dell'API Traffic Director al tuo indirizzo IP di Secure Web Proxy:

    gcloud dns record-sets create "trafficdirector.REGION.rep.googleapis.com." \
 --project="PROJECT_ID" \
 --zone="td-swp-zone" \
 --type="A" \
 --ttl=300 \
 --rrdatas="${SWP_IP}"

  4. Verifica che il set di record DNS sia attivo nella zona privata:

    gcloud dns record-sets list \
 --project="PROJECT_ID" \
 --zone="td-swp-zone"

    Verifica che il record A per trafficdirector.REGION.rep.googleapis.com. si risolva nel tuo indirizzo IP di Secure Web Proxy.

Con i Controlli di servizio VPC

Per gli ambienti dei Controlli di servizio VPC, esegui il provisioning di un endpoint regionale di Private Service Connect che ha come target l'API Traffic Director regionale all'interno della subnet VPC e mappa il dominio utilizzando una zona Cloud DNS privata:

  1. Crea un endpoint regionale di Private Service Connect che abbia come target l'API Traffic Director regionale:

    gcloud network-connectivity regional-endpoints create td-rep-endpoint \
 --project="PROJECT_ID" \
 --region="REGION" \
 --network="projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME" \
 --subnetwork="projects/PROJECT_ID/regions/REGION/subnetworks/VPC_SUBNET_NAME" \
 --target-google-api="trafficdirector.REGION.rep.googleapis.com"

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto Google Cloud .
    • REGION: la regione del deployment.
    • VPC_NETWORK_NAME: il nome della tua rete VPC.
    • VPC_SUBNET_NAME: il nome della tua subnet VPC.

  2. Recupera l'indirizzo IP interno dell'endpoint regionale:

    TD_ENDPOINT_IP=$(gcloud network-connectivity regional-endpoints describe td-rep-endpoint \
 --project="PROJECT_ID" \
 --region="REGION" \
 --format="value(address)")

  3. Crea una zona Cloud DNS gestita privata per l'API Traffic Director:

    gcloud dns managed-zones create td-psc-zone \
 --project="PROJECT_ID" \
 --dns-name="trafficdirector.REGION.rep.googleapis.com." \
 --description="Private DNS zone for regional endpoint" \
 --visibility="private" \
 --networks="VPC_NETWORK_NAME"

  4. Aggiungi un record A che risolva il dominio regionale dell'API Traffic Director nell'indirizzo IP dell'endpoint regionale:

    gcloud dns record-sets create "trafficdirector.REGION.rep.googleapis.com." \
 --project="PROJECT_ID" \
 --zone="td-psc-zone" \
 --type="A" \
 --ttl=300 \
 --rrdatas="${TD_ENDPOINT_IP}"

  5. Verifica l'endpoint regionale e il set di record DNS:

    gcloud dns record-sets list \
 --project="PROJECT_ID" \
 --zone="td-psc-zone"

    Verifica che il record A per trafficdirector.REGION.rep.googleapis.com. punti all'indirizzo IP dell'endpoint regionale.

Esegui il deployment o aggiorna un servizio Cloud Run con Ambient Networking e traffico in uscita VPC diretto

Per connettere l'agente Cloud Run all'istanza Secure Web Proxy nella tua rete VPC, abilita sia il traffico VPC diretto in uscita sia l'Ambient Networking regionale e configura il servizio con un'identità agente. Quando esegui il deployment con --functional-type=agent e --identity-type=agent-identity, Cloud Run concede roles/run.agentDefaultAccess, che include le autorizzazioni roles/trafficdirector.client e roles/cloudtrace.agent:

  1. Esegui il deployment di un nuovo servizio agente Cloud Run o aggiorna un servizio esistente per abilitare l'Ambient Networking regionale, il traffico in uscita VPC diretto per tutto il traffico in uscita e l'identità dell'agente:

    Nuovo servizio

    gcloud beta run deploy SERVICE_NAME \
 --image=IMAGE_URL \
 --network=VPC_NETWORK_NAME \
 --subnet=VPC_SUBNET_NAME \
 --vpc-egress=all \
 --functional-type=agent \
 --identity-type=agent-identity \
 --ambient-networking \
 --set-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
 --region=REGION \
 --project=PROJECT_ID

    Servizio esistente

    gcloud beta run services update SERVICE_NAME \
 --network=VPC_NETWORK_NAME \
 --subnet=VPC_SUBNET_NAME \
 --vpc-egress=all \
 --functional-type=agent \
 --identity-type=agent-identity \
 --ambient-networking \
 --update-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
 --region=REGION \
 --project=PROJECT_ID

    Sostituisci quanto segue:

    • SERVICE_NAME: il nome del tuo servizio agente Cloud Run.
    • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest. Se utilizzi Artifact Registry, il repository REPO_NAME deve essere già stato creato. L'URL segue il formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
    • VPC_NETWORK_NAME: il nome della rete VPC che ospita l'istanza di Secure Web Proxy. Per informazioni sulla creazione di una rete VPC e di una subnet, consulta Crea e gestisci le reti VPC.
    • VPC_SUBNET_NAME: il nome della subnet VPC in cui è raggiungibile l'istanza di Secure Web Proxy.
    • REGION: la regione del servizio.
    • PROJECT_ID: il tuo ID progetto Google Cloud .

  2. Verifica che il servizio Cloud Run utilizzi Ambient Networking, il traffico VPC diretto in uscita e l'identità dell'agente:

    gcloud beta run services describe SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID

    Verifica che l'output mostri la subnet di traffico in uscita VPC diretto, il traffico in uscita all-traffic, l'Ambient Networking regionale e l'entità dell'identità dell'agente assegnata.

Configura l'agente Cloud Run in modo che consideri attendibile Agent Gateway

Affinché Secure Web Proxy possa ispezionare i payload HTTPS e applicare le policy, deve terminare le sessioni TLS in uscita dall'agente. Il container dell'agente Cloud Run deve considerare attendibile il certificato dell'autorità di certificazione (CA) radice o subordinata associato alla policy di ispezione TLS di Secure Web Proxy in CA Service o alla PKI della tua azienda privata:

  1. Esporta il certificato CA con codifica PEM dal pool di Certificate Authority Service per la tua istanza di Secure Web Proxy:

    gcloud privateca pools get-ca-certs CA_POOL_NAME \
   --location=REGION \
   --project=PROJECT_ID \
   --output-file=agent-gateway-root.crt

    Sostituisci quanto segue:

    • CA_POOL_NAME: il nome del pool CA associato alla policy di ispezione TLS di Secure Web Proxy.
    • REGION: la regione del pool CA.
    • PROJECT_ID: il tuo ID progetto Google Cloud .

  2. Aggiorna il servizio Cloud Run per passare i contenuti del certificato in una variabile di ambiente:

    gcloud beta run services update SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID \
   --update-env-vars="AGENT_GATEWAY_ROOT_CERT=$(cat agent-gateway-root.crt)"

    Sostituisci quanto segue:

    • SERVICE_NAME: il nome del tuo servizio agente Cloud Run.
    • REGION: la regione del servizio.
    • PROJECT_ID: il tuo ID progetto Google Cloud .

    Ad esempio, il seguente script entrypoint del container Debian o Ubuntu, entrypoint.sh, installa AGENT_GATEWAY_ROOT_CERT nell'archivio di attendibilità del sistema ed esporta i percorsi del bundle CA per i client Python e gRPC prima di avviare l'applicazione:

    #!/usr/bin/env bash
set -e
if [ -n "${AGENT_GATEWAY_ROOT_CERT}" ]; then
 printf '%s\n' "${AGENT_GATEWAY_ROOT_CERT}" > /usr/local/share/ca-certificates/agent-gateway.crt
 update-ca-certificates
 export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
 export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
 export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/etc/ssl/certs/ca-certificates.crt
fi
exec "$@"

  3. Verifica che il servizio imposti la variabile di ambiente AGENT_GATEWAY_ROOT_CERT:

    gcloud beta run services describe SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID \
   --format="yaml(spec.template.spec.containers[0].env)"

Instrada il traffico in uscita verso Agent Gateway

Dopo aver configurato il servizio Cloud Run e l'Agent Gateway, crea una policy EgressRouting dell'API Network Services per indirizzare il traffico in uscita dal servizio Cloud Run al gateway Secure Web Proxy:

  1. Crea la risorsa EgressRouting:

    gcloud alpha network-services egress-routings create my-run-egress-routing \
   --location=REGION \
   --project=PROJECT_ID \
   --gateway="//networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME" \
   --sources="workloadUri=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME"

    Sostituisci quanto segue:

    • REGION: la regione del servizio Cloud Run e del gateway.
    • PROJECT_ID: il tuo ID progetto Google Cloud .
    • SWP_NAME: il nome della risorsa Secure Web Proxy Gateway sottostante, non della risorsa AgentGateway.
    • SERVICE_NAME: il nome del tuo servizio agente Cloud Run. Per instradare tutti i servizi Cloud Run nel progetto tramite il gateway con un'unica policy, imposta workloadUri su //run.googleapis.com/projects/PROJECT_ID o //run.googleapis.com/projects/PROJECT_NUMBER.

    Dopo l'applicazione di EgressRouting, tutto il traffico in uscita dal tuo servizio Cloud Run viene instradato tramite Secure Web Proxy. Configura le policy nella sezione successiva per consentire e gestire le richieste in uscita.

  2. Verifica che la risorsa EgressRouting sia attiva:

    gcloud alpha network-services egress-routings describe my-run-egress-routing \
   --location=REGION \
   --project=PROJECT_ID

    Verifica che sources elenchi l'URI del workload Cloud Run e che gateway faccia riferimento alla risorsa gateway Secure Web Proxy.

Configura le policy su Agent Gateway

Dopo aver instradato il traffico in uscita tramite Agent Gateway, gestisci le richieste in uscita dell'agente collegando policy di autorizzazione e associazioni di estensioni di Service Extensions alla risorsa Agent Gateway:

  • Traffico di base e filtro degli strumenti MCP: consenti gli endpoint del modello e i metodi e gli strumenti Model Context Protocol (MCP) approvati utilizzando le policy di autorizzazione di ALLOW.
  • Controllo degli accessi basato sull'identità: associa IAP a una risorsa ExtensionBinding e configura una policy di accesso unificato IAM per controllare quali agenti possono chiamare server, strumenti o endpoint MCP specifici.
  • Sicurezza dei contenuti: associa Model Armor a una risorsa ExtensionBinding per ispezionare e sanificare prompt e risposte per prompt injection, fuga di dati sensibili o violazioni delle policy.

Le policy di autorizzazione o le regole delle policy di sicurezza del gateway associate alla risorsa Secure Web Proxy Gateway sottostante vengono ignorate. Dopo aver creato o aggiornato una risorsa ExtensionBinding, la propagazione delle modifiche al gateway può richiedere fino a cinque minuti. Per la sequenza di valutazione delle regole tra regole di rete, ispezione TLS, associazioni di estensioni e regole HTTP, consulta Ordine di valutazione per le regole di autorizzazione.

Consenti il traffico in uscita di base e il traffico MCP

Per impostazione predefinita, Secure Web Proxy nega tutto il traffico in uscita con errori 403 Forbidden finché un ALLOW AuthzPolicy sulla risorsa Agent Gateway non lo consente.

Poiché il tuo servizio Cloud Run utilizza --vpc-egress=all, tutto il traffico dei container in uscita, incluse le chiamate allo strumento MCP e le richieste LLM, viene instradato tramite il gateway. Collega le policy di autorizzazione ALLOW alla risorsa Agent Gateway per entrambi i tipi di traffico:

Configura le policy in uscita di IAP

Agent Gateway utilizza IAP come motore di decisione delle policy per valutare le Unified Access Policies IAM. Per applicare le policy di identità degli agenti, definisci le regole di accesso in una policy di accesso unificato IAM e associa IAP al tuo gateway:

  1. Crea una policy di accesso unificato IAM utilizzando l'entità Agent Identity del tuo servizio Cloud Run, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME, e associa la policy al tuo progetto o gateway seguendo le istruzioni riportate in Crea policy di accesso IAM e Associa una policy di accesso unificato a un progetto.
  2. Associa IAP, iap.googleapis.com, al tuo Agent Gateway con un ExtensionBinding seguendo le istruzioni riportate in Associa IAP al tuo Agent Gateway.

Poiché --vpc-egress=all invia chiamate ai modelli come REGION-aiplatform.googleapis.com tramite il gateway, imposta l'ambito matchConditions in IAP ExtensionBinding su prefix: "urn:mcp" in modo che le chiamate ai modelli bypassino la valutazione di IAP. Per gestire anche il traffico da agente ad agente, aggiungi prefix: "urn:agent". Se l'associazione dell'estensione corrisponde ad altri host, aggiungi una regola di autorizzazione per ogni host nella policy Unified Access Policies IAM, ad esempio destination.unregistered.host == 'REGION-aiplatform.googleapis.com'. Per un esempio, consulta Crea una policy per gli endpoint da agente a non registrato.

Configura le policy di Model Armor

Per ispezionare e sanificare i prompt e le risposte che passano attraverso il tuo Agent Gateway, crea template Model Armor e associali al gateway:

  1. Crea template di richiesta e risposta Model Armor regionali e concedi i ruoli richiesti all'agente di servizio Service Extensions seguendo le istruzioni riportate in Configura Model Armor su un gateway.
  2. Collega i modelli al tuo Agent Gateway con un ExtensionBinding seguendo le istruzioni riportate in Associa Model Armor per la sanitizzazione di prompt e risposte.

Configura un deployment tra progetti centralizzato con VPC condiviso

In un'organizzazione con più progetti, puoi eseguire il deployment degli agenti Cloud Run in uno o più progetti di servizio, ospitando al contempo un Agent Gateway, un'istanza di Secure Web Proxy e un Agent Registry in un progetto host di networking dedicato utilizzando il VPC condiviso:

  • Progetto A, progetto di servizio dell'agente: ospita il servizio dell'agente Cloud Run e la policy EgressRouting locale.
  • Progetto B, progetto host di gateway e networking: funge da progetto host del VPC condiviso e deve ospitare l'Agent Gateway, l'istanza Secure Web Proxy, l'Agent Registry, le risorse ExtensionBinding e le associazioni delle policy IAM.
Diagramma dell'architettura tra progetti che mostra il Progetto A che ospita un servizio Cloud Run e una policy di routing in uscita, connesso tramite una rete VPC condiviso al Progetto B che ospita Agent Gateway, Secure Web Proxy e Agent Registry.
Figura 2. Deployment di Agent Gateway tra progetti utilizzando il VPC condiviso.

Prima di iniziare questi passaggi, abilita run.googleapis.com, compute.googleapis.com, networkservices.googleapis.com e trafficdirector.googleapis.com nel Progetto A, insieme a aiplatform.googleapis.com se l'agente esegue chiamate agentiche a Vertex AI. Nel Progetto B, esegui il deployment dell'istanza Secure Web Proxy e della risorsa Agent Gateway sulla rete VPC condiviso come descritto in Crea un Agent Gateway autogestito e configura il routing DNS o Private Service Connect come descritto in Configura Ambient Networking di Cloud Run per accedere all'API Traffic Director in modo che i sidecar ambient nel Progetto A possano raggiungere l'API Traffic Director.

Per configurare un deployment tra progetti, completa i seguenti passaggi:

  1. Configura il progetto B come progetto host del VPC condiviso, collega il progetto A come progetto di servizio e condividi la subnet che ospita l'istanza di Secure Web Proxy. L'abilitazione del VPC condiviso e il collegamento dei progetti di servizio richiedono roles/compute.xpnAdmin a livello di organizzazione o di cartella. Per istruzioni, consulta Invia il traffico a una rete VPC condivisa con traffico in uscita VPC diretto e Esegui il provisioning del VPC condiviso.

  2. Nel progetto B, concedi roles/compute.networkUser sulla subnet condivisa al service agent Cloud Run del progetto A:

    gcloud compute networks subnets add-iam-policy-binding SHARED_SUBNET_NAME \
   --project=PROJECT_B_ID \
   --region=REGION \
   --member="serviceAccount:service-PROJECT_A_NUMBER@serverless-robot-prod.iam.gserviceaccount.com" \
   --role="roles/compute.networkUser"

    Sostituisci quanto segue:

    • SHARED_SUBNET_NAME: il nome della subnet condivisa nel progetto B.
    • PROJECT_B_ID: l'ID progetto del progetto B, il progetto host del gateway e del VPC condiviso.
    • REGION: la regione della subnet condivisa.
    • PROJECT_A_NUMBER: il numero di progetto del Progetto A, il progetto di servizio dell'agente.

  3. Esegui il deployment del servizio agente Cloud Run nel Progetto A che punta alla subnet condivisa nel Progetto B:

    gcloud beta run deploy SERVICE_NAME \
   --project=PROJECT_A_ID \
   --image=IMAGE_URL \
   --subnet=projects/PROJECT_B_ID/regions/REGION/subnetworks/SHARED_SUBNET_NAME \
   --vpc-egress=all \
   --functional-type=agent \
   --identity-type=agent-identity \
   --ambient-networking \
   --set-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
   --region=REGION

    Sostituisci quanto segue:

    • SERVICE_NAME: il nome del tuo servizio agente Cloud Run nel Progetto A.
    • PROJECT_A_ID: l'ID progetto del Progetto A, il progetto di servizio dell'agente.
    • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest. Se utilizzi Artifact Registry, il repository REPO_NAME deve essere già stato creato. L'URL segue il formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.

    Dopo aver eseguito il deployment del servizio, configura l'agente nel Progetto A in modo che consideri attendibile il certificato della CA radice dell'istanza Secure Web Proxy nel Progetto B seguendo i passaggi descritti in Configura l'agente Cloud Run in modo che consideri attendibile Agent Gateway.

  4. Crea una policy EgressRouting nel Progetto A che faccia riferimento al gateway Secure Web Proxy nel Progetto B. Devi avere roles/networkservices.admin nel Progetto A:

    gcloud alpha network-services egress-routings create my-central-egress-routing \
   --location=REGION \
   --project=PROJECT_A_ID \
   --gateway="//networkservices.googleapis.com/projects/PROJECT_B_ID/locations/REGION/gateways/CENTRAL_SWP_NAME" \
   --sources="workloadUri=//run.googleapis.com/projects/PROJECT_A_ID/locations/REGION/services/SERVICE_NAME"

    Sostituisci CENTRAL_SWP_NAME con il nome del gateway Secure Web Proxy nel progetto B. Per instradare tutti i servizi Cloud Run nel Progetto A tramite il gateway del Progetto B, imposta workloadUri su //run.googleapis.com/projects/PROJECT_A_ID o //run.googleapis.com/projects/PROJECT_A_NUMBER.

  5. Verifica che la risorsa EgressRouting tra progetti sia attiva nel Progetto A:

    gcloud alpha network-services egress-routings describe my-central-egress-routing \
   --location=REGION \
   --project=PROJECT_A_ID

  6. Configura le policy di base centralizzate, IAP e Model Armor sulla risorsa Agent Gateway nel Progetto B come descritto in Configura le policy su Agent Gateway:

    • Consenti il traffico MCP e del modello di base sulla risorsa Agent Gateway nel Progetto B seguendo le istruzioni riportate in Consenti il traffico in uscita e MCP di base.
    • Per autorizzare l'agente nel Progetto A a chiamare i server MCP registrati nel Progetto B, crea una policy Unified Access Policies IAM nel Progetto B il cui elenco principals faccia riferimento al numero di progetto del Progetto A, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_A_NUMBER/locations/REGION/services/SERVICE_NAME, associa la policy al Progetto B o alla relativa risorsa Agent Gateway e collega l'IAP ExtensionBinding nel Progetto B.
    • Per applicare i guardrail centralizzati di Model Armor nel Progetto B, crea i template Model Armor regionali, concedi i ruoli richiesti all'agente di servizio di Service Extensions del Progetto B e collega ExtensionBinding di Model Armor alla risorsa Agent Gateway nel Progetto B.

Visualizza log e tracce

Le interazioni degli agenti in uscita instradate tramite Agent Gateway generano log e tracce distribuite in modo da poter monitorare le decisioni relative alle norme ed eseguire il debug del comportamento degli agenti:

Se le richieste in uscita non vanno a buon fine o bypassano il gateway, consulta Risolvi i problemi di Agent Gateway.

Aree geografiche supportate

Puoi utilizzare Agent Gateway su Cloud Run nelle seguenti regioni:

  • europe-west1
  • us-central1

Limitazioni

Oltre alle limitazioni di Ambient Networking e alle considerazioni su Secure Web Proxy in Esegui il deployment di Secure Web Proxy come Agent Gateway, quando utilizzi Agent Gateway con Cloud Run si applicano le seguenti limitazioni:

  • Le richieste degli agenti in uscita instradate tramite un'istanza Secure Web Proxy con ispezione TLS agli endpoint *.mtls.googleapis.com e *.mtls.run.app non vanno a buon fine con errori 503 perché Secure Web Proxy termina e riavvia le sessioni TLS senza inoltrare il certificato client.
  • Ogni Agent Gateway autogestito regionale supporta al massimo un Agent Registry regionale nel suo elenco registries.
  • Per impostazione predefinita, ogni progetto supporta fino a 10 risorse AgentGateway regionali e 10 risorse EgressRouting regionali per regione. I nuovi progetti potrebbero iniziare con un limite di 2 per regione. Per richiedere un aumento della quota, contatta il team dedicato all'account.
  • Devi esportare il certificato radice o subordinato dal pool di Certificate Authority Service o dalla PKI aziendale privata e configurare il container dell'agente in modo che lo consideri attendibile.

Passaggi successivi