Integrazione SWP di Agent Engine (ADK) PSC

1. Introduzione

Un'interfaccia Private Service Connect è una risorsa che consente a una rete Virtual Private Cloud (VPC) producer di avviare connessioni a varie destinazioni in una rete VPC consumer. Le reti producer e consumer possono trovarsi in progetti e organizzazioni diversi.

Se un collegamento di rete accetta una connessione da un'interfaccia Private Service Connect, Google Cloud assegna all'interfaccia un indirizzo IP da una subnet consumer specificata dal collegamento di rete. Le reti consumer e producer sono connesse e possono comunicare utilizzando indirizzi IP interni.

Una connessione tra un collegamento di rete e un'interfaccia Private Service Connect è simile alla connessione tra un endpoint Private Service Connect e un collegamento al servizio, ma presenta due differenze fondamentali:

  • Un collegamento di rete consente a una rete producer di avviare connessioni a una rete consumer (uscita del servizio gestito), mentre un endpoint consente a una rete consumer di avviare connessioni a una rete producer (ingresso del servizio gestito).
  • Una connessione di interfaccia Private Service Connect è transitiva. Ciò significa che una rete producer può comunicare con altre reti connesse alla rete consumer.

Considerazioni sull'accessibilità dell'interfaccia PSC di Vertex AI

  • L'interfaccia PSC è in grado di instradare il traffico verso destinazioni VPC o on-premise apprese dalla rete VPC.
  • Per limitare l'ambito della raggiungibilità dalla connessione di rete utilizzata da Agent Engine alla rete VPC, l'implementazione delle regole firewall di uscita è la best practice.
  • Per limitare l'ambito del traffico in uscita dalla rete proveniente dalla subnet di collegamento di rete di Agent Engine, deve essere implementata una regola firewall in uscita VPC. Questa regola consentirà esplicitamente il traffico da Agent Engine al SWP, negando tutto il resto del traffico in uscita.

Considerazioni su Vertex AI PSC-Interface VPC-SC

  • Per il funzionamento dell'interfaccia PSC di Agent Engine, devi fornire la connettività in uscita a internet all'interno del VPC del cliente, anche se i Controlli di servizio VPC sono abilitati.

Secure Web Proxy

Secure Web Proxy è un servizio gestito e nativo del cloud che offre controllo granulare e sicurezza per il traffico in uscita (HTTP/HTTPS). Funge da gateway centrale, consentendoti di applicare criteri di sicurezza alle connessioni avviate da Agent Engine di cui è stato eseguito il deployment con l'interfaccia PSC alle risorse VPC, come VM, GKE, internet e ambienti multicloud.

Cosa risolve

  • Impedisce l'esfiltrazione di dati:blocca i caricamenti o le comunicazioni non autorizzati con siti dannosi.
  • Impone la conformità:garantisce che il traffico in uscita rispetti le norme di sicurezza e di gestione dei dati della tua organizzazione.
  • Riduce l'overhead operativo:in quanto servizio completamente gestito, Secure Web Proxy elimina la necessità di eseguire il deployment, lo scaling o la manutenzione delle tue VM proxy.
  • Fornisce una visibilità approfondita:consente l'ispezione del traffico criptato con Transport Layer Security (TLS) per rilevare minacce nascoste.

Per ulteriori informazioni, consulta le seguenti risorse:

Esegui il deployment di un agente | AI generativa su Vertex AI | Google Cloud

Configura un'interfaccia Private Service Connect per le risorse Vertex AI | Google Cloud

Cosa creerai

In questo tutorial, creerai un Agent Engine completo di cui è stato eseguito il deployment con l'interfaccia Private Service Connect (PSC) integrata con SWP per eseguire le seguenti operazioni utilizzando le librerie ADK:

  • Esegui il deployment del peering DNS in Agent Engine per risolvere il nome di dominio completo dei proxy di servizio utilizzato nella configurazione del proxy.
  • Consenti la connettività a un sito pubblico (https://api.frankfurter.app/) tramite un proxy web sicuro di cui è stato eseguito il deployment nel VPC del consumer con un indirizzo RFC1918.
  • Consenti il traffico dalla subnet di collegamento di rete al proxy web e nega tutto il resto.

Figura 1

565e9eb07ef18f44.png

Cosa imparerai a fare

  • Come creare un collegamento di rete
  • Come un producer può utilizzare un collegamento di rete per creare un'interfaccia PSC
  • Come stabilire la comunicazione dal producer al consumer utilizzando il peering DNS
  • Come eseguire il deployment e utilizzare un SWP per il traffico in uscita da internet
  • Come definire regole firewall in uscita per ridurre la raggiungibilità di rete di Agent Engine

Che cosa ti serve

Progetto Google Cloud

Autorizzazioni IAM

2. Prima di iniziare

Aggiornare il progetto per supportare il tutorial

Questo tutorial utilizza le variabili $per facilitare l'implementazione della configurazione di gcloud in Cloud Shell.

In Cloud Shell, esegui le seguenti operazioni:

gcloud config set project [YOUR-PROJECT-NAME]
projectid=YOUR-PROJECT-NAME
echo $projectid

Abilitazione delle API

In Cloud Shell, esegui le seguenti operazioni:

gcloud services enable "compute.googleapis.com"
gcloud services enable "aiplatform.googleapis.com"
gcloud services enable "dns.googleapis.com"
gcloud services enable "notebooks.googleapis.com"
gcloud services enable "storage.googleapis.com"
gcloud services enable "iap.googleapis.com"
gcloud services enable "networksecurity.googleapis.com"
gcloud services enable "networkservices.googleapis.com"
gcloud services enable "cloudresourcemanager.googleapis.com"

Verifica che le API siano state abilitate correttamente

gcloud services list --enabled

3. Configurazione consumatore

Crea il VPC consumer

Questo VPC si trova in un progetto cliente. In questo VPC verranno create le seguenti risorse

  • Subnet consumer
  • Subnet del collegamento di rete
  • Subnet solo proxy
  • Regole firewall
  • Cloud DNS

In Cloud Shell, esegui le seguenti operazioni:

gcloud compute networks create consumer-vpc --project=$projectid --subnet-mode=custom

Crea le subnet consumer

In Cloud Shell, crea la subnet per il file SWP:

gcloud compute networks subnets create swp-subnet --project=$projectid --range=10.10.10.0/28 --network=consumer-vpc --region=us-central1 --enable-private-ip-google-access

Crea la subnet del collegamento di rete Private Service Connect

In Cloud Shell, crea la subnet per il collegamento di rete PSC:

gcloud compute networks subnets create intf-subnet --project=$projectid --range=192.168.10.0/28 --network=consumer-vpc --region=us-central1 --enable-private-ip-google-access

Crea la subnet proxy regionale

In Cloud Shell, crea la subnet solo proxy richiesta per i prodotti basati su Envoy, come Secure Web Proxy e i bilanciatori del carico delle applicazioni interni/esterni regionali. Il flag –purpose deve essere impostato su REGIONAL_MANAGED_PROXY:

gcloud compute networks subnets create proxy-subnet \
  --purpose=REGIONAL_MANAGED_PROXY \
  --role=ACTIVE \
  --region=us-central1 \
  --network=consumer-vpc \
  --range=100.100.10.0/26

Crea la subnet del notebook

In Cloud Shell, crea la subnet per l'istanza notebook:

gcloud compute networks subnets create notebook-subnet --project=$projectid --range=192.168.20.0/28 --network=consumer-vpc --region=us-central1 --enable-private-ip-google-access

4. Crea Secure Web Proxy

La modalità esplicita (o modalità di routing proxy esplicito) di Secure Web Proxy è un metodo di deployment in cui i carichi di lavoro client devono essere configurati in modo esplicito per utilizzare l'indirizzo IP interno o il nome di dominio completo e la porta di SWP come proxy di inoltro.

Questa policy conterrà le regole che regolano il traffico tramite il proxy web sicuro in base a una corrispondenza di sessione, host() == 'api.frankfurter.app' e corrispondenza dell'applicazione request.method == 'GET'

Nei passaggi riportati di seguito, assicurati di modificare YOUR-PROJECT-ID con il tuo ID progetto.

In Cloud Shell, crea un file policy.yaml:

cat > policy.yaml << EOF
name: projects/$projectid/locations/us-central1/gatewaySecurityPolicies/my-swp-policy 
description: "My basic SWP policy" 
EOF

In Cloud Shell, importa il criterio:

gcloud network-security gateway-security-policies import my-swp-policy \
    --source=policy.yaml \
    --location=us-central1

Creare regole Secure Web Proxy

Definisci regole all'interno del criterio per specificare quale traffico è consentito o negato. Le regole vengono valutate in base alla priorità.

In Cloud Shell, crea un file rule.yaml per consentire l'accesso all'endpoint internet utilizzato da Agent Engine, api.frankfurter.app:

cat > rule.yaml << EOF
name: "projects/$projectid/locations/us-central1/gatewaySecurityPolicies/my-swp-policy/rules/allow-example"
description: "Allow frankfurter API"
enabled: true
priority: 10
basicProfile: ALLOW
sessionMatcher: "host() == 'api.frankfurter.app'"
EOF

In Cloud Shell, genera la regola della policy di sicurezza:

gcloud network-security gateway-security-policies rules import allow-example \
    --source=rule.yaml \
    --location=us-central1 \
    --gateway-security-policy=my-swp-policy

Creare regole Secure Web Proxy

L'istanza SWP, di cui viene eseguito il deployment in modalità di routing esplicito, deve essere creata in modo che Agent Engine debba specificare l'indirizzo IP o l'FQDN di SWP all'interno della configurazione del proxy ADK, come definito nel file YAML del gateway. Questa configurazione collega anche l'istanza alla policy, alla rete e alla subnet corrispondenti.

In Cloud Shell, crea un file gateway.yaml utilizzato per il deployment del SWP.

Assicurati di salvare il file YAML dopo aver aggiornato le seguenti variabili con i dettagli del tuo ambiente: PROJECT_ID, REGION, NETWORK_NAME e PROXY_ONLY_SUBNET_NAME. La porta 8888 specificata è la porta del tunnel esterno mappata alla configurazione del proxy all'interno di Agent Engine.

cat > gateway.yaml << EOF
name: "projects/$projectid/locations/us-central1/gateways/my-swp-instance"
type: SECURE_WEB_GATEWAY
ports: [8888]
addresses: ["10.10.10.5"]
gatewaySecurityPolicy: "projects/$projectid/locations/us-central1/gatewaySecurityPolicies/my-swp-policy"
network: "projects/$projectid/global/networks/consumer-vpc"
subnetwork: "projects/$projectid/regions/us-central1/subnetworks/swp-subnet"
routingMode: EXPLICIT_ROUTING_MODE
EOF

In Cloud Shell, importa il gateway:

gcloud network-services gateways import my-swp-instance \
    --source=gateway.yaml \
    --location=us-central1

5. Collegamento di rete Private Service Connect

I collegamenti di rete sono risorse regionali che rappresentano il lato consumer di un'interfaccia Private Service Connect. Associ un'unica subnet a un collegamento di rete e il producer assegna gli IP all'interfaccia Private Service Connect da quella subnet. La subnet deve trovarsi nella stessa regione del collegamento di rete. Un collegamento di rete deve trovarsi nella stessa regione del servizio producer.

Crea il collegamento di rete

In Cloud Shell, crea il collegamento di rete.

gcloud compute network-attachments create psc-network-attachment \
    --region=us-central1 \
    --connection-preference=ACCEPT_AUTOMATIC \
    --subnets=intf-subnet

Elenca i collegamenti di rete

In Cloud Shell, elenca il collegamento di rete.

gcloud compute network-attachments list

Descrivi i collegamenti di rete

In Cloud Shell, descrivi il collegamento di rete.

gcloud compute network-attachments describe psc-network-attachment --region=us-central1

Prendi nota del nome del collegamento di rete PSC, psc-network-attachment, che verrà utilizzato dal producer durante la creazione dell'interfaccia Private Service Connect.

Per visualizzare l'URL dell'allegato di rete PSC in Cloud Console, vai a:

Network Services → Private Service Connect → Network Attachment → psc-network-attachment

15f80b46c3a0332d.png

6. Zona DNS privata

Creerai una zona Cloud DNS per demo.com e la compilerai con un record A che rimanda agli indirizzi IP dei tuoi SWP. In seguito, il peering DNS verrà implementato in Agent Engine, il che consentirà l'accesso ai record DNS del consumer.

In Cloud Shell, esegui questo comando per creare un nome DNS demo.com.

gcloud dns --project=$projectid managed-zones create private-dns-codelab --description="" --dns-name="demo.com." --visibility="private" --networks="https://compute.googleapis.com/compute/v1/projects/$projectid/global/networks/consumer-vpc"

Ottieni e memorizza gli indirizzi IP del SWP utilizzati per il record A DNS.

In Cloud Shell, esegui un comando describe su swp, my-swp-instance:

gcloud network-services gateways describe my-swp-instance --location=us-central1

In Cloud Shell, crea il set di record per SWP, swp.demo.com, assicurati di aggiornare l'indirizzo IP in base all'output del tuo ambiente.

gcloud dns --project=$projectid record-sets create swp.demo.com. --zone="private-dns-codelab" --type="A" --ttl="300" --rrdatas="10.10.10.5"

Configurazione del firewall

Crea una regola Cloud Firewall per consentire l'accesso dall'interfaccia PSC

Nella sezione seguente, crea una regola firewall che consenta al traffico proveniente dall'allegato di rete PSC di accedere alla subnet SWP nel VPC consumer. Per una maggiore sicurezza, puoi specificare l'indirizzo IP SWP come unica destinazione.

In Cloud Shell, crea la regola firewall in uscita che consente l'accesso dall'allegato di rete a SWP:

gcloud compute firewall-rules create allow-access-to-swp \
    --network=consumer-vpc \
    --action=ALLOW \
    --rules=ALL \
    --direction=EGRESS \
    --priority=1000 \
    --source-ranges="192.168.10.0/28" \
    --destination-ranges="10.10.10.5/32" \
    --enable-logging

In Cloud Shell, crea la regola firewall in uscita che nega tutto il traffico dall'allegato di rete:

gcloud compute firewall-rules create deny-all \
    --network=consumer-vpc \
    --action=DENY \
    --rules=ALL \
    --direction=EGRESS \
    --priority=65534 \
    --source-ranges="192.168.10.0/28" \
    --destination-ranges="0.0.0.0/0" \
    --enable-logging

7. Crea una policy firewall per la rete VPC per garantire la Threat Intelligence:

Nella sezione seguente, crea una policy firewall che ti consenta di sfruttare gli elenchi di minacce gestiti di Google per bloccare i siti dannosi noti prima che il traffico venga ricevuto dal proxy di sicurezza web.

In Cloud Shell, crea la policy di firewall globale:

gcloud compute network-firewall-policies create psc-secure-policy \
    --global \
    --description="Policy to protect VPC with Threat Intelligence"

In Cloud Shell, associa la policy al tuo VPC:

gcloud compute network-firewall-policies associations create \
    --firewall-policy=psc-secure-policy \
    --network=consumer-vpc \
    --name=psc-swp-association \
    --global-firewall-policy

In Cloud Shell, aggiungi le regole di Threat Intelligence:

Queste regole interromperanno il traffico verso attori dannosi noti prima di avviare il traffico dall'agente. In questo esempio, abbiamo aggiunto regole per bloccare i nodi di uscita Tor (in uscita), gli IP dannosi noti (in uscita), i proxy anonimi noti(in uscita) e i miner di criptovalute per impedire l'utilizzo non autorizzato delle risorse (in uscita).

gcloud compute network-firewall-policies rules create 100 \
    --firewall-policy=psc-secure-policy \
    --action=deny \
    --direction=EGRESS \
    --dest-threat-intelligence=iplist-tor-exit-nodes \
    --layer4-configs=all \
    --enable-logging \
    --description="Block anonymous Tor traffic" \
    --global-firewall-policy

gcloud compute network-firewall-policies rules create 110 \
    --firewall-policy=psc-secure-policy \
    --action=deny \
    --direction=EGRESS \
    --dest-threat-intelligence=iplist-known-malicious-ips \
    --layer4-configs=all \
    --enable-logging \
    --description="Block known botnets and malware sources" \
    --global-firewall-policy

gcloud compute network-firewall-policies rules create 120 \
    --firewall-policy=psc-secure-policy \
    --action=deny \
    --direction=EGRESS \
    --dest-threat-intelligence=iplist-anon-proxies \
    --layer4-configs=all \
    --enable-logging \
    --description="Block Known Anonymous Proxies" \
    --global-firewall-policy

gcloud compute network-firewall-policies rules create 130 \
    --firewall-policy=psc-secure-policy \
    --action=deny \
    --direction=EGRESS \
    --dest-threat-intelligence=iplist-crypto-miners \
    --layer4-configs=all \
    --enable-logging \
    --description="Block Crypto Miners (Prevent unauthorized resource usage)" \
    --global-firewall-policy

8. Crea un notebook Jupyter

La sezione seguente ti guida nella creazione di un blocco note Jupyter. Questo notebook verrà utilizzato per eseguire il deployment di Agent Engine che ha come target un proxy esplicito per l'uscita da internet.

Crea un service account gestito dall'utente

Nella sezione seguente creerai un service account che verrà associato all'istanza di Vertex AI Workbench utilizzata nel tutorial.

Nel tutorial, al service account verranno applicati i seguenti ruoli:

In Cloud Shell, crea il service account.

gcloud iam service-accounts create notebook-sa \
    --display-name="notebook-sa"

In Cloud Shell, aggiorna il service account con il ruolo Storage Admin.

gcloud projects add-iam-policy-binding $projectid --member="serviceAccount:notebook-sa@$projectid.iam.gserviceaccount.com" --role="roles/storage.admin"

In Cloud Shell, aggiorna il service account con il ruolo Utente Vertex AI.

gcloud projects add-iam-policy-binding $projectid --member="serviceAccount:notebook-sa@$projectid.iam.gserviceaccount.com" --role="roles/aiplatform.user"

In Cloud Shell, aggiorna il service account con il ruolo Amministratore di Artifact Registry.

gcloud projects add-iam-policy-binding $projectid --member="serviceAccount:notebook-sa@$projectid.iam.gserviceaccount.com" --role="roles/artifactregistry.admin"

In Cloud Shell, consenti al service account del notebook di utilizzare il service account predefinito di Compute Engine.

gcloud iam service-accounts add-iam-policy-binding \
    $(gcloud projects describe $(gcloud config get-value project) --format='value(projectNumber)')-compute@developer.gserviceaccount.com \
    --member="serviceAccount:notebook-sa@$projectid.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountUser"

9. Crea un'istanza di Vertex AI Workbench

Nella sezione seguente, crea un'istanza di Vertex AI Workbench che incorpori il service account creato in precedenza, notebook-sa.

In Cloud Shell, crea l'istanza private-client.

gcloud workbench instances create workbench-tutorial --vm-image-project=cloud-notebooks-managed --vm-image-family=workbench-instances --machine-type=n1-standard-4 --location=us-central1-a --subnet-region=us-central1 --subnet=notebook-subnet --disable-public-ip --shielded-secure-boot=true --shielded-integrity-monitoring=true --shielded-vtpm=true --service-account-email=notebook-sa@$projectid.iam.gserviceaccount.com

Aggiungi un'altra regola nel proxy web sicuro esistente per inoltrare il traffico da questa istanza del blocco note:

In Cloud Shell, crea il file rule-notebook.yaml utilizzando un editor di testo e assicurati di aggiornare il file YAML con il tuo ID progetto.

cat > rule-notebook.yaml << EOF
name: projects/$projectid/locations/us-central1/gatewaySecurityPolicies/my-swp-policy/rules/allow-notebook-subnet
description: Allow Internet access for notebook subnet
enabled: true
priority: 2
basicProfile: ALLOW
sessionMatcher: inIpRange(source.ip,'192.168.20.2')
EOF

In Cloud Shell, genera la regola della policy di sicurezza:

gcloud network-security gateway-security-policies rules import allow-notebook-subnet \
    --source=rule-notebook.yaml \
    --location=us-central1 \
    --gateway-security-policy=my-swp-policy

10. Aggiornamento di Vertex AI Service Agent

Vertex AI agisce per tuo conto per eseguire operazioni come l'ottenimento di un indirizzo IP dalla subnet di collegamento di rete PSC utilizzata per creare l'interfaccia PSC. A questo scopo, Vertex AI utilizza un service agent (elencato di seguito) che richiede l'autorizzazione Network Admin:

service-$projectnumber@gcp-sa-aiplatform.iam.gserviceaccount.com

In Cloud Shell, ottieni il numero del progetto.

gcloud projects describe $projectid | grep projectNumber

In Cloud Shell, imposta il numero del progetto.

projectnumber=YOUR-PROJECT-NUMBER

In Cloud Shell, crea un service account per AI Platform. Salta questo passaggio se hai un service account esistente nel tuo progetto.

gcloud beta services identity create --service=aiplatform.googleapis.com --project=$projectnumber

In Cloud Shell, aggiorna l'account service agent con il ruolo compute.networkAdmin.

gcloud projects add-iam-policy-binding $projectid --member="serviceAccount:service-$projectnumber@gcp-sa-aiplatform.iam.gserviceaccount.com" --role="roles/compute.networkAdmin"

In Cloud Shell, aggiorna l'account service agent con il ruolo dns.peer

gcloud projects add-iam-policy-binding $projectid --member="serviceAccount:service-$projectnumber@gcp-sa-aiplatform.iam.gserviceaccount.com" --role="roles/dns.peer"

Aggiornamento del service account predefinito

Concedi al service account predefinito l'accesso a Vertex AI. Tieni presente che la propagazione della modifica dell'accesso potrebbe richiedere un po' di tempo.

In Cloud Shell, aggiorna il service account predefinito con il ruolo aiplatform.user

gcloud projects add-iam-policy-binding $projectid \
  --member="serviceAccount:$projectnumber-compute@developer.gserviceaccount.com" \
    --role="roles/aiplatform.user"

11. Esegui il deployment di Agent Engine

Nota: utilizzeremo la console GCP e il blocco note JupyterLab per completare le attività in questa sezione

Nella sezione seguente, creerai un notebook che esegue le seguenti attività:

  • Utilizza l'API Frankfurter (https://api.frankfurter.app/) per ottenere i dati sui tassi di cambio
  • Fa riferimento a un proxy esplicito (proxy_server) che ha come target l'SWP nel VPC dei consumer utilizzando il nome di dominio completo swp.demo.com
  • Definisci dnsPeeringConfigs "domain": "demo.com."

Esegui il job di addestramento nell'istanza di Vertex AI Workbench.

  • Nella console Google Cloud, vai a Vertex AI → Workbench
  • Accanto al nome dell'istanza di Vertex AI Workbench (workbench-tutorial), fai clic su Apri JupyterLab. L'istanza di Vertex AI Workbench si apre in JupyterLab.
  • Seleziona File > New > Notebook
  • Seleziona Kernel > Python 3

Installa le librerie Python necessarie: installa le librerie richieste per Agent Engine, tra cui pyyaml, google-cloud-aiplatform, cloudpickle, google-cloud-api-keys e langchain-google-vertexai.

Nel notebook JupyterLab, crea una nuova cella ed esegui il seguente comando specificando l'indirizzo IP di SWP

7b827a6a38bb5afc.png

!pip install --proxy http://10.10.10.5:8888 --upgrade google-cloud-aiplatform[agent_engines,adk]

Definisci le seguenti variabili in base al tuo ambiente nello snippet di codice seguente:

  • PROJECT_ID
  • BUCKET_NAME
  • AGENT_NAME

In questo lab, utilizzerai le variabili BUCKET_NAME e AGENT_NAME per inizializzare e configurare il bucket di archiviazione disponibile a livello globale.

Nella sezione seguente viene definito PROXY_SERVER, ad esempio swp.demo.com, che richiede il peering DNS per la risoluzione dei nomi. Nella configurazione, AGENT_PEER_DOMAIN viene implementato come demo.com, che corrisponde alla zona DNS privata creata in un passaggio precedente all'interno di AGENT_PEER_NETWORK, consumer-vpc.

Nel notebook JupyterLab, crea una nuova cella ed esegui il seguente comando:

# --- Fundamental Project Configuration ---
PROJECT_ID = "YOUR_PROJECT_ID"
LOCATION = "us-central1" # e.g., "us-central1"
BUCKET_NAME = "YOUR_BUCKET_NAME" # A GCS bucket in the same location

# --- Agent Configuration ---
AGENT_NAME = "YOUR_AGENT_NAME"
MODEL = "gemini-2.5-flash" # Or another suitable model

# --- Network and Proxy Configuration ---
# The agent will call the Frankfurter API via this proxy
PROXY_SERVER = "http://swp.demo.com:8888"

# --- Deployment Configuration (PSC & DNS Peering) ---
# This should be a pre-existing Network Attachment
NETWORK_ATTACHMENT_NAME = f"projects/{PROJECT_ID}/regions/{LOCATION}/networkAttachments/psc-network-attachment"
# Optional DNS Peering config
AGENT_PEER_DOMAIN = "demo.com."
AGENT_PEER_NETWORK = "consumer-vpc"

# --- Initialize Vertex AI SDK ---
import vertexai
STAGING_BUCKET = f"gs://{BUCKET_NAME}"

vertexai.init(project=PROJECT_ID, location=LOCATION, staging_bucket=STAGING_BUCKET)

print(f"Vertex AI SDK initialized for project {PROJECT_ID} in {LOCATION}.")

Nel notebook JupyterLab, crea una nuova cella ed esegui il seguente codice.

!adk create $AGENT_NAME --model=$MODEL --project=$PROJECT_ID --region=$LOCATION

Nel notebook JupyterLab, crea una nuova cella ed esegui il seguente comando per creare la variabile proxy che corrisponde al nome di dominio completo e alla porta di SWP.

import os
os.environ["PROXY_SERVER_URL"] = "http://swp.demo.com:8888"

La seguente cella di codice mostra la configurazione proxy esplicita per Agent Engine per accedere all'endpoint internet api.frankfurter.app specificando il proxy di servizio (SWP), utilizzando PROXY_SERVER_TO_USE che mappa a os.environ["PROXY_SERVER_URL"].

import requests
# Use the globally defined proxy server URL
    proxies = {
       "http": PROXY_SERVER_TO_USE,
       "https": PROXY_SERVER_TO_USE,
    }
    try:
        response = requests.get(
            f"https://api.frankfurter.app/{currency_date}",
            params={"from": currency_from, "to": currency_to},
            proxies=proxies,
) 
response.raise_for_status() 
print(response.json()) 
except requests.exceptions.RequestException as e: print(f"An error occurred: {e}")

Nel notebook JupyterLab, crea una nuova cella ed esegui il seguente codice che definisce l'implementazione dello strumento per l'API di targeting per il cambio di valuta api.frankfurther.app.

%%writefile $AGENT_NAME/agent.py
from google.adk.agents.llm_agent import Agent
import os
import requests


# Get Proxy Server URL
# This is the VM's FQDN to reach the proxy vm in the consumers network
if "PROXY_SERVER_URL" not in os.environ:
    raise ValueError("Missing required environment variable: PROXY_SERVER_URL is not set.")
PROXY_SERVER_TO_USE = os.environ["PROXY_SERVER_URL"]

# Mock tool implementation
def get_exchange_rate(
    currency_from: str = "USD",
    currency_to: str = "EUR",
    currency_date: str = "latest",
):
    """Retrieves the exchange rate between two currencies on a specified date.

    Uses the Frankfurter API (https://api.frankfurter.app/) to obtain
    exchange rate data.

    Args:
        currency_from: The base currency (3-letter currency code).
            Defaults to "USD" (US Dollar).
        currency_to: The target currency (3-letter currency code).
            Defaults to "EUR" (Euro).
        currency_date: The date for which to retrieve the exchange rate.
            Defaults to "latest" for the most recent exchange rate data.
            Can be specified in YYYY-MM-DD format for historical rates.

    Returns:
        dict: A dictionary containing the exchange rate information.
            Example: {"amount": 1.0, "base": "USD", "date": "2023-11-24",
                "rates": {"EUR": 0.95534}}
    """
    # Use the globally defined proxy server URL
    proxies = {
       "http": PROXY_SERVER_TO_USE,
       "https": PROXY_SERVER_TO_USE,
    }
    
    try:
        response = requests.get(
            f"https://api.frankfurter.app/{currency_date}",
            params={"from": currency_from, "to": currency_to},
            proxies=proxies,
        )
        response.raise_for_status()  # Raise an error for bad responses
        return response.json()
    except Exception as e:
        return f"An unexpected error occurred: {e}"

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description="Provides the currency exchange rates between two currencies",
    instruction="You are a helpful assistant that provides the currency exchange rates between two currencies. Use the 'get_exchange_rate' tool for this purpose.",
    tools=[get_exchange_rate],
)

Nel notebook JupyterLab, crea una nuova cella ed esegui il seguente codice.

# 1. Set your variables
CURRENCY_DATE="latest"
CURRENCY_FROM="USD"
CURRENCY_TO="EUR"
PROXY_SERVER="http://swp.demo.com:8888"

# 2. Run the curl command
!curl -x "$PROXY_SERVER" "https://api.frankfurter.app/$CURRENCY_DATE?from=$CURRENCY_FROM&to=$CURRENCY_TO"

Nel notebook JupyterLab, crea una nuova cella ed esegui il seguente comando che richiama la configurazione dell'interfaccia PSC utilizzata da Agent Engine, oltre al peering DNS.

import json
import os

CONFIG_FILE_PATH = os.path.join(AGENT_NAME, ".agent_engine_config.json")
# Create your config as a Python dictionary ---
config_data = {
    "requirements": [
        "google-cloud-aiplatform[agent_engines,adk]",
        "requests",
    ],
    "psc_interface_config": {
        "network_attachment": NETWORK_ATTACHMENT_NAME,
        "dns_peering_configs": [
            {
                "domain": AGENT_PEER_DOMAIN,
                "target_project": PROJECT_ID,
                "target_network": AGENT_PEER_NETWORK,
            },
        ],
    },
}

# Write the dictionary to a JSON file ---
os.makedirs(AGENT_NAME, exist_ok=True) # Ensure the directory exists
with open(CONFIG_FILE_PATH, 'w') as f:
    json.dump(config_data, f, indent=4)

print(f"Successfully created {CONFIG_FILE_PATH} with your variables.")

Nel notebook JupyterLab, crea una nuova cella ed esegui il seguente codice.

import json
import os

CONFIG_FILE_PATH = os.path.join(AGENT_NAME, ".agent_engine_config.json")
# Create your config as a Python dictionary ---
config_data = {

    "psc_interface_config": {
        "network_attachment": NETWORK_ATTACHMENT_NAME,
        "dns_peering_configs": [
            {
                "domain": AGENT_PEER_DOMAIN,
                "target_project": PROJECT_ID,
                "target_network": AGENT_PEER_NETWORK,
            },
        ],
    },
}

# Write the dictionary to a JSON file ---
os.makedirs(AGENT_NAME, exist_ok=True) # Ensure the directory exists
with open(CONFIG_FILE_PATH, 'w') as f:
    json.dump(config_data, f, indent=4)

print(f"Successfully created {CONFIG_FILE_PATH} with your variables.")

Nel notebook JupyterLab, crea una nuova cella ed esegui il seguente codice.

%%writefile $AGENT_NAME/.env

GOOGLE_CLOUD_PROJECT=PROJECT_ID
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_VERTEXAI=1


PROXY_SERVER_URL=http://swp.demo.com:8888

Nel notebook JupyterLab, crea una nuova cella ed esegui il seguente codice che crea l'agente.

!adk deploy agent_engine $AGENT_NAME --staging_bucket=$STAGING_BUCKET --env_file=$AGENT_NAME/.env --agent_engine_config_file=$AGENT_NAME/.agent_engine_config.json --display_name=$AGENT_NAME

Un ID motore di ragionamento verrà generato al momento dell'esecuzione della cella. Per il passaggio successivo, avrai bisogno dell'ID generato, che in questo esempio è 3235268984265768960.

✅ Created agent engine: projects/9315891080/locations/us-central1/reasoningEngines/3235268984265768960

Nel blocco note JupyterLab, crea una nuova cella ed esegui il seguente comando, assicurandoti di aggiornarlo con il numero di progetto e l'ID di ragionamento di Agent Engine dell'output precedente:

from vertexai import agent_engines
remote_app = agent_engines.get("projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/ENTER_YOUR_ID")

Nel notebook JupyterLab, crea una nuova cella ed esegui il seguente codice.

def print_event_nicely_with_thoughts(event):
    """
    Parses and prints streaming query events, including thoughts.
    """
    try:
        content = event.get('content', {})
        role = content.get('role')
        parts = content.get('parts', [{}])

        if not parts:
            print("...")
            return

        part = parts[0] # Get the first part

        # Event 1: Model is thinking (calling a tool or just text)
        if role == 'model':

            # Check for and print any explicit 'thought' text
            if 'thought' in part:
                print(f"🧠 Thought: {part['thought']}")

            # Check for a function call
            if 'function_call' in part:
                # If we haven't *already* printed an explicit thought,
                # print a generic one.
                if 'thought' not in part:
                    print("🧠 Thinking... (decided to use a tool)")

                call = part['function_call']
                print(f"   🔧 Tool Call: {call.get('name')}()")
                print(f"      Args: {call.get('args')}")

            # Check for the final text answer
            elif 'text' in part:
                text = part.get('text', '')
                print(f"\n💬 Model: {text}")

        # Event 2: The tool returns its result
        elif role == 'user' and 'function_response' in part:
            resp = part['function_response']
            print(f"⚙️ Tool Response (from {resp.get('name')}):")
            print(f"   Output: {resp.get('response')}")

        # Other event types (like progress messages)
        else:
            print("...") # Show progress for other events

    except Exception as e:
        print(f"Error processing event: {e}")
        # print(f"Raw event: {event}") # Uncomment to debug



for event in remote_app.stream_query(
    user_id="u_456",
    # session_id=remote_session["id"],
    message="Provide USD to INR conversion rate",
):
    print_event_nicely_with_thoughts(event)

Esempio di esecuzione riuscita che convalida la connettività all'endpoint pubblico api.frankfurther.app tramite SWP in base al tasso di conversione da USD a INR.

f9f925983ab5cc9d.png

12. Convalida dell'interfaccia PSC

Puoi anche visualizzare gli IP di collegamento di rete utilizzati da Agent Engine accedendo a:

Servizi di rete → Private Service Connect → Collegamento di rete → psc-network-attachment

Seleziona il progetto tenant (il nome del progetto termina con -tp)

c9c412334a7f5ad9.png

Il campo evidenziato indica l'indirizzo IP utilizzato da Agent Engine dall'allegato di rete PSC.

e94c6c03fb51f7fe.png

13. SWP - Cloud Logging Validation

Per visualizzare Cloud Logging e convalidare l'uscita da internet eseguita da SWP, vai a:

Monitoraggio → Esplora log

Inserisci la query: resource.type=" networkservices.googleapis.com/Gateway" poi fai clic su Esegui query. Di seguito è riportato un esempio che conferma l'endpoint di destinazione, api.frankfurter.app.

f53831ef8ec663db.png

fc154a5b22da2a87.png

Il seguente esempio di Cloud Logging convalida quanto segue:

Destination_range: indirizzo IP dell'interfaccia PSC di Agent Engine

Source_range: subnet solo proxy Dest_ip: indirizzo IP di Secure Web Proxy

Assicurati di modificare project_id per la query Cloud Logging.

logName:("projects/project_id/logs/compute.googleapis.com%2Ffirewall") AND jsonPayload.rule_details.reference:("network:consumer-vpc/firewall:allow-access-to-swp")

{
  "insertId": "1j9ym95fmu8g6o",
  "jsonPayload": {
    "vpc": {
      "project_id": "XXXXXXXXXXXXX",
      "subnetwork_name": "intf-subnet",
      "vpc_name": "consumer-vpc"
    },
    "rule_details": {
      "destination_range": [
        "10.10.10.5/32"
      ],
      "reference": "network:consumer-vpc/firewall:allow-access-to-swp",
      "priority": 1000,
      "source_range": [
        "192.168.10.0/28"
      ],
      "direction": "EGRESS",
      "ip_port_info": [
        {
          "ip_protocol": "ALL"
        }
      ],
      "action": "ALLOW"
    },
    "disposition": "ALLOWED",
    "remote_instance": {
      "region": "us-central1"
    },
    "remote_vpc": {
      "vpc_name": "consumer-vpc",
      "project_id": "XXXXXXXXXXXXXXX",
      "subnetwork_name": "swp-subnet"
    },
    "connection": {
      "src_ip": "192.168.10.2",
      "src_port": 48640,
      "dest_port": 8888,
      "dest_ip": "10.10.10.5",
      "protocol": 6
    }
  },
  "resource": {
    "type": "gce_subnetwork",
    "labels": {
      "subnetwork_id": "7147084067647653041",
      "project_id": "XXXXXXXXXXXXXX",
      "location": "us-central1",
      "subnetwork_name": "intf-subnet"
    }
  },
  "timestamp": "2025-12-30T12:51:36.628538815Z",
  "logName": "projects/dec30-run1-agent/logs/compute.googleapis.com%2Ffirewall",
  "receiveTimestamp": "2025-12-30T12:51:40.846652708Z"
}

14. Esegui la pulizia

Nel notebook JupyterLab, crea una nuova cella ed esegui il seguente comando che attiverà l'eliminazione del deployment di Agent Engine.

Assicurati di aggiornare "project number" e "reasoningEngines token".

import requests
token = !gcloud auth application-default print-access-token
ENDPOINT = "https://us-central1-aiplatform.googleapis.com"
response = requests.delete(
    f"{ENDPOINT}/v1beta1/projects/218166745590/locations/us-central1/reasoningEngines/3086854705725308928",
    params={"force": "true"},
    headers={
        "Content-Type": "application/json; charset=utf-8",
        "Authorization": f"Bearer {token[0]}"
    },
)
print(response.text)

Da Cloud Shell, elimina i componenti del tutorial.

gcloud workbench instances delete workbench-tutorial --project=$projectid --location=us-central1-a

gcloud network-security gateway-security-policies rules delete allow-notebook-subnet \
    --gateway-security-policy=my-swp-policy \
    --location=us-central1

gcloud network-security gateway-security-policies rules delete allow-example \
    --gateway-security-policy=my-swp-policy \
    --location=us-central1

gcloud network-security gateway-security-policies delete my-swp-policy \
    --location=us-central1
gcloud network-services gateways delete my-swp-instance\
    --location=us-central1

gcloud dns record-sets delete swp.demo.com --zone=private-dns-codelab  --type=A

gcloud dns managed-zones delete private-dns-codelab


gcloud compute network-attachments delete psc-network-attachment --region=us-central1 --quiet

export ROUTER_NAME=$(gcloud compute routers list --regions=us-central1 \
    --filter="name ~ swg-autogen-router" --format="value(name)")


 gcloud compute routers nats delete swg-autogen-nat --router=$ROUTER_NAME --region=us-central1 --quiet 

gcloud compute routers delete $ROUTER_NAME --region=us-central1 --quiet

gcloud compute networks subnets delete intf-subnet rfc1918-subnet1 --region=us-central1 --quiet

gcloud compute networks subnets delete intf-subnet swp-subnet
 --region=us-central1 --quiet

gcloud compute networks subnets delete intf-subnet intf-subnet --region=us-central1 --quiet

gcloud compute networks subnets delete intf-subnet proxy-subnet
 --region=us-central1 --quiet

gcloud compute networks subnets delete intf-subnet notebook-subnet
--region=us-central1 --quiet

gcloud compute networks delete consumer-vpc --quiet

15. Complimenti

Congratulazioni, hai configurato e convalidato correttamente Agent Engine di cui è stato eseguito il deployment con l'interfaccia Private Service Connect con traffico internet in uscita eseguito tramite un proxy esplicito.

Hai creato l'infrastruttura consumer e hai aggiunto un collegamento di rete che ha consentito al producer di creare una VM con più NIC per collegare la comunicazione tra consumer e producer. Hai imparato a creare un peering proxy e DNS esplicito che consentisse la connettività a internet.

Cosmopup pensa che i tutorial siano fantastici.

e6d3675ca7c6911f.jpeg

Passaggi successivi

Ulteriori letture e video

Documentazione di riferimento