Integração do PSC SWP do Agent Engine (ADK)

1. Introdução

A interface do Private Service Connect é um recurso que permite que uma rede de nuvem privada virtual (VPC, na sigla em inglês) do produtor inicie conexões com vários destinos em uma rede VPC do consumidor. As redes de produtor e consumidor podem estar em diferentes projetos e organizações.

Se um anexo de rede aceitar uma conexão de uma interface do Private Service Connect, o Google Cloud alocará à interface um endereço IP de uma sub-rede do consumidor especificada pelo anexo de rede. As redes de consumidores e produtores estão conectadas e podem se comunicar por endereços IP internos.

Uma conexão entre um anexo de rede e uma interface do Private Service Connect é semelhante à conexão entre um endpoint do Private Service Connect e um anexo de serviço, mas há duas diferenças principais:

  • Um anexo de rede permite que uma rede produtora inicie conexões com uma rede consumidora (saída de serviço gerenciada), enquanto um endpoint permite que uma rede consumidora inicie conexões com uma rede produtora (entrada de serviço gerenciada).
  • Uma conexão de interface do Private Service Connect é transitiva. Isso significa que uma rede do produtor pode se comunicar com outras que estão conectadas à rede do consumidor.

Considerações sobre a acessibilidade da interface do PSC da Vertex AI

  • A interface do PSC é capaz de rotear o tráfego para destinos baseados em VPC ou locais aprendidos pela rede VPC.
  • Para limitar o escopo de capacidade de alcance do anexo de rede usado pelo Agent Engine à rede VPC, a implementação de regras de firewall de saída é a prática recomendada.
  • Para limitar o escopo do tráfego de saída da rede originado da sub-rede de anexação de rede do Agent Engine, uma regra de firewall de saída da VPC precisa ser implantada. Essa regra permite explicitamente o tráfego do Agent Engine para o SWP, negando todo o outro tráfego de saída.

Considerações sobre a VPC-SC da interface do PSC da Vertex AI

  • Você precisa fornecer conectividade de saída da Internet na VPC do cliente para que a interface PSC do Agent Engine funcione, mesmo que o VPC Service Controls esteja ativado.

Proxy seguro da Web

O Secure Web Proxy é um serviço gerenciado nativo da nuvem que oferece controle granular e segurança para seu tráfego de saída (HTTP/HTTPS). Ele funciona como um gateway central, permitindo que você aplique políticas de segurança em conexões iniciadas pelo Agent Engine implantado com a interface PSC em recursos da VPC, como VMs, GKE, Internet e ambientes multicloud.

O que ele resolve

  • Evita a exfiltração de dados:bloqueia uploads não autorizados ou a comunicação com sites maliciosos.
  • Aplica a conformidade:garante que o tráfego de saída obedeça às políticas de segurança e tratamento de dados da sua organização.
  • Reduz a sobrecarga operacional:como um serviço totalmente gerenciado, o Secure Web Proxy elimina a necessidade de implantar, escalonar ou manter suas próprias VMs de proxy.
  • Oferece visibilidade detalhada:permite a inspeção do tráfego criptografado com Transport Layer Security (TLS) para detectar ameaças ocultas.

Para mais informações, consulte os seguintes recursos:

Implantar um agente | IA generativa na Vertex AI | Google Cloud

Configurar uma interface do Private Service Connect para recursos da Vertex AI | Google Cloud

O que você vai criar

Neste tutorial, você vai criar um Agent Engine abrangente implantado com a interface do Private Service Connect (PSC) integrada ao SWP para realizar o seguinte usando as bibliotecas do ADK:

  • Implante o peering de DNS no Agent Engine para resolver o nome de domínio totalmente qualificado dos SWPs usado na configuração de proxy.
  • Permita a conectividade com um site público (https://api.frankfurter.app/) por um Secure Web Proxy implantado na VPC do consumidor com um endereço RFC1918.
  • Permita o tráfego da sub-rede de anexação de rede para o SWP, negando todo o restante.

Figura 1.

565e9eb07ef18f44.png

O que você vai aprender

  • Como criar um anexo de rede
  • Como um produtor pode usar um anexo de rede para criar uma interface do PSC
  • Como estabelecer comunicação do produtor para o consumidor usando o peering de DNS
  • Como implantar e usar um SWP para saída da Internet
  • Como definir regras de firewall de saída para reduzir a capacidade de alcance da rede do Agent Engine

O que é necessário

Projeto do Google Cloud

Permissões do IAM

2. Antes de começar

Atualizar o projeto para oferecer suporte ao tutorial

Este tutorial usa $variables para ajudar na implementação da configuração do gcloud no Cloud Shell.

No Cloud Shell, faça o seguinte:

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

Ativação da API

No Cloud Shell, faça o seguinte:

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"

Verificar se as APIs foram ativadas com sucesso

gcloud services list --enabled

3. Configuração do consumidor

Criar a VPC do consumidor

Essa VPC reside em um projeto do cliente. Os seguintes recursos serão criados nesta VPC:

  • Sub-rede do consumidor
  • Sub-rede de anexo de rede
  • Sub-rede somente proxy
  • Regras de firewall
  • Cloud DNS

No Cloud Shell, faça o seguinte:

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

Criar as sub-redes do consumidor

No Cloud Shell, crie a sub-rede para o 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

Criar a sub-rede de anexo de rede do Private Service Connect

No Cloud Shell, crie a sub-rede para a vinculação de rede do 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

Criar a sub-rede proxy regional

No Cloud Shell, crie a sub-rede somente proxy necessária para produtos baseados no Envoy, como o Secure Web Proxy e os balanceadores de carga de aplicativo internos/externos regionais. A flag "–purpose" precisa ser definida como 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

Criar a sub-rede do notebook

No Cloud Shell, crie a sub-rede para a instância de 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. Criar um Secure Web Proxy

O modo explícito do Secure Web Proxy (ou modo de roteamento de proxy explícito) é um método de implantação em que as cargas de trabalho do cliente precisam ser configuradas explicitamente para usar o endereço IP interno ou o nome de domínio totalmente qualificado e a porta do SWP como proxy de encaminhamento.

Essa política vai conter as regras que regem o tráfego pelo proxy seguro da Web com base em uma correspondência de sessão, host() == 'api.frankfurter.app' e de aplicativo request.method == 'GET'.

Nas etapas abaixo, modifique YOUR-PROJECT-ID para o ID do seu projeto.

No Cloud Shell, crie um arquivo policy.yaml:

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

No Cloud Shell, importe a política:

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

Criar regras do Secure Web Proxy

Defina regras na política para especificar qual tráfego é permitido ou negado. As regras são avaliadas com base na prioridade.

No Cloud Shell, crie um arquivo rule.yaml para permitir o acesso ao endpoint da Internet usado pelo mecanismo de agente, 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

No Cloud Shell, gere a regra da política de segurança:

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

Criar regras do Secure Web Proxy

A instância do SWP, que é implantada no modo de roteamento explícito, precisa ser criada para que o Agent Engine especifique o endereço IP ou o FQDN do SWP na configuração de proxy do ADK, conforme definido no arquivo YAML do gateway. Essa configuração também vincula a instância à política, rede e sub-rede correspondentes.

No Cloud Shell, crie um arquivo gateway.yaml usado para implantar o SWP.

Salve o arquivo YAML depois de atualizar as seguintes variáveis com os detalhes do seu ambiente: PROJECT_ID, REGION, NETWORK_NAME e PROXY_ONLY_SUBNET_NAME. A porta 8888 especificada é a porta do túnel externo mapeada para a configuração de proxy no 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

No Cloud Shell, importe o gateway:

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

5. Anexo de rede do Private Service Connect

Os anexos de rede são recursos regionais que representam o lado do consumidor de uma interface do Private Service Connect. Você associa uma única sub-rede a um anexo de rede, e o produtor atribui IPs à interface do Private Service Connect a partir dessa sub-rede. A sub-rede precisa estar na mesma região do anexo de rede. Um anexo de rede precisa estar na mesma região do serviço do produtor.

Criar o anexo de rede

No Cloud Shell, crie o anexo de rede.

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

Listar os anexos de rede

No Cloud Shell, liste o anexo de rede.

gcloud compute network-attachments list

Descrever os anexos de rede

No Cloud Shell, descreva o anexo de rede.

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

Anote o nome do anexo de rede do PSC, psc-network-attachment, que será usado pelo produtor ao criar a interface do Private Service Connect.

Para ver o URL de anexo de rede do PSC no console do Cloud, navegue até:

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

15f80b46c3a0332d.png

6. Zona de DNS particular

Você vai criar uma zona do Cloud DNS para demo.com e preenchê-la com um registro A que aponta para os endereços IP dos SWPs. Depois, o peering de DNS será implantado no Agent Engine, o que permitirá o acesso aos registros de DNS do consumidor.

No Cloud Shell, execute o seguinte comando para criar um nome de 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"

Obtenha e armazene os endereços IP do SWP usados para o registro A de DNS.

No Cloud Shell, execute uma descrição em swp, my-swp-instance:

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

No Cloud Shell, crie o conjunto de registros para o SWP, swp.demo.com, e atualize o endereço IP com base na saída do seu ambiente.

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

Configuração do firewall

Crie uma regra de firewall do Cloud para permitir o acesso da interface do PSC

Na seção a seguir, crie uma regra de firewall que permita o tráfego originado do acesso ao anexo de rede do PSC à sub-rede SWP na VPC do consumidor. Para aumentar a segurança, especifique o endereço IP do SWP como o único destino.

No Cloud Shell, crie a regra de firewall de saída que permite o acesso do anexo de rede ao 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

No Cloud Shell, crie a regra de firewall de saída que nega todo o tráfego da conexão de rede:

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. Crie uma política de firewall para a rede VPC e garanta a inteligência de ameaças:

Na seção a seguir, crie uma política de firewall que permita usar as listas de ameaças gerenciadas do Google para bloquear sites maliciosos conhecidos antes do tráfego recebido pelo SWP.

No Cloud Shell, crie a política de firewall global:

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

No Cloud Shell, associe a política à sua VPC:

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

No Cloud Shell, adicione as regras de inteligência de ameaças:

Essas regras descartam o tráfego para agentes maliciosos conhecidos antes de iniciar o tráfego do agente. Neste exemplo, adicionamos regras para bloquear nós de saída do Tor (saída), bloquear IPs maliciosos conhecidos (saída), bloquear proxies anônimos conhecidos(saída) e bloquear mineradores de criptomoedas para evitar o uso não autorizado de recursos (saída).

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. Crie um notebook do Jupyter

A seção a seguir orienta você na criação de um notebook do Jupyter. Este notebook será usado para implantar o Agent Engine direcionando um proxy explícito para saída da Internet.

Criar uma conta de serviço gerenciada pelo usuário

Na seção a seguir, você vai criar uma conta de serviço que será associada à instância do Vertex AI Workbench usada no tutorial.

No tutorial, a conta de serviço terá os seguintes papéis aplicados:

No Cloud Shell, crie a conta de serviço.

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

No Cloud Shell, atualize a conta de serviço com o papel de administrador do Storage.

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

No Cloud Shell, atualize a conta de serviço com a função de usuário da Vertex AI.

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

No Cloud Shell, atualize a conta de serviço com o papel Administrador do Artifact Registry.

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

No Cloud Shell, permita que a conta de serviço do notebook use a conta de serviço padrão do 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. criar uma instância do Vertex AI Workbench

Na seção a seguir, crie uma instância do Vertex AI Workbench que incorpore a conta de serviço criada anteriormente, notebook-sa.

No Cloud Shell, crie a instância 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

Adicione outra regra ao Secure Web Proxy atual para encaminhar o tráfego desta instância de notebook:

No Cloud Shell, crie o arquivo rule-notebook.yaml usando um editor de texto e atualize o YAML com o ID do projeto.

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

No Cloud Shell, gere a regra da política de segurança:

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. Atualização do agente de serviço da Vertex AI

A Vertex AI age em seu nome para realizar operações como a obtenção de um endereço IP da sub-rede de anexo de rede do PSC usada para criar a interface do PSC. Para isso, a Vertex AI usa um agente de serviço (listado abaixo) que exige a permissão de administrador de rede:

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

No Cloud Shell, obtenha o número do projeto.

gcloud projects describe $projectid | grep projectNumber

No Cloud Shell, defina o número do projeto.

projectnumber=YOUR-PROJECT-NUMBER

No Cloud Shell, crie uma conta de serviço para o AI Platform. Pule esta etapa se você já tiver uma conta de serviço no projeto.

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

No Cloud Shell, atualize a conta do agente de serviço com a função compute.networkAdmin.

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

No Cloud Shell, atualize a conta do agente de serviço com a função dns.peer

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

Atualização da conta de serviço padrão

Conceda à sua conta de serviço padrão acesso à Vertex AI. Pode levar algum tempo para a mudança no acesso ser propagada.

No Cloud Shell, atualize a conta de serviço padrão com a função aiplatform.user

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

11. Implantar o Agent Engine

Observação:vamos usar o console do GCP e o notebook do JupyterLab para concluir as tarefas desta seção.

Na seção a seguir, você vai criar um notebook que realiza as seguintes tarefas:

  • Usa a API Frankfurter (https://api.frankfurter.app/) para receber dados de taxa de câmbio.
  • Faz referência a um proxy explícito (proxy_server) segmentando o SWP na VPC dos consumidores usando o FQDN swp.demo.com.
  • Defina dnsPeeringConfigs "domain": "demo.com."

Execute o job de treinamento na instância do Vertex AI Workbench.

  • No console do Google Cloud, navegue até Vertex AI → Workbench
  • Ao lado do nome da instância do Vertex AI Workbench (workbench-tutorial), clique em "Abrir JupyterLab". A instância do Vertex AI Workbench será aberta no JupyterLab.
  • Selecionar File > New > Notebook
  • Selecionar Kernel > Python 3

Instale as bibliotecas necessárias do Python: instale as bibliotecas necessárias para o Agent Engine, incluindo pyyaml, google-cloud-aiplatform, cloudpickle, google-cloud-api-keys e langchain-google-vertexai.

No notebook do JupyterLab, crie uma célula e execute o seguinte comando, especificando o endereço IP do SWP:

7b827a6a38bb5afc.png

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

Defina as seguintes variáveis com base no seu ambiente no snippet de código a seguir:

  • PROJECT_ID
  • BUCKET_NAME
  • AGENT_NAME

Neste laboratório, você vai usar as variáveis BUCKET_NAME e AGENT_NAME para inicializar e configurar seu bucket de armazenamento disponível globalmente.

Na seção a seguir, o PROXY_SERVER é definido, por exemplo, swp.demo.com, que exige peering de DNS para resolução de nomes. Na configuração, o AGENT_PEER_DOMAIN é implantado como demo.com, que corresponde à zona de DNS particular criada em uma etapa anterior na AGENT_PEER_NETWORK, consumer-vpc.

No notebook do JupyterLab, crie uma célula e execute o seguinte:

# --- 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}.")

No notebook do JupyterLab, crie uma célula e execute o seguinte:

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

No notebook do JupyterLab, crie uma nova célula e execute o seguinte comando para criar a variável de proxy que corresponde ao FQDN e à porta do SWP.

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

A célula de código a seguir demonstra a configuração explícita de proxy para o Agent Engine acessar a API de endpoint da Internet api.frankfurter.app especificando o SWP, usando PROXY_SERVER_TO_USE que mapeia para 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}")

No notebook do JupyterLab, crie uma célula e execute o seguinte código, que define a implementação da ferramenta para a API de segmentação de câmbio 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],
)

No notebook do JupyterLab, crie uma célula e execute o seguinte:

# 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"

No notebook do JupyterLab, crie uma célula e execute o seguinte comando, que invoca a configuração da interface psc usada pelo Agent Engine, além do peering de 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.")

No notebook do JupyterLab, crie uma célula e execute o seguinte:

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.")

No notebook do JupyterLab, crie uma célula e execute o seguinte:

%%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

No notebook do JupyterLab, crie uma nova célula e execute o seguinte código para criar o 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

Um ID do mecanismo de raciocínio será gerado na execução da célula. Para a próxima etapa, você vai precisar do ID gerado, que é 3235268984265768960 neste exemplo.

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

No notebook do JupyterLab, crie uma célula e execute o seguinte, atualizando com o número do projeto e o ID de raciocínio do Agent Engine da saída anterior:

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

No notebook do JupyterLab, crie uma célula e execute o seguinte:

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)

Exemplo de uma execução bem-sucedida que valida a conectividade com o endpoint público api.frankfurther.app pelo SWP com base na taxa de conversão de USD para INR.

f9f925983ab5cc9d.png

12. Validação da interface do PSC

Também é possível conferir os IPs de vinculação de rede usados pelo Agent Engine navegando até:

Serviços de rede → Private Service Connect → Anexo de rede → psc-network-attachment

Selecione o projeto de locatário (nome do projeto que termina em -tp).

c9c412334a7f5ad9.png

O campo destacado indica o endereço IP usado pelo Agent Engine no anexo de rede do PSC.

e94c6c03fb51f7fe.png

13. SWP - Validação do Cloud Logging

Para validar a saída da Internet realizada pelo SWP, acesse o Cloud Logging:

Monitoramento → Análise de registros

Insira a consulta: resource.type=" networkservices.googleapis.com/Gateway" e clique em "Executar consulta". Confira abaixo um exemplo que confirma o endpoint de destino, api.frankfurter.app.

f53831ef8ec663db.png

fc154a5b22da2a87.png

O exemplo do Cloud Logging a seguir valida o seguinte:

Destination_range: endereço IP da interface do PSC do Agent Engine

Source_range: Proxy Only Subnet Dest_ip: Secure Web Proxy IP Address

Mude o project_id da consulta do 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. Limpar

No notebook do JupyterLab, crie uma célula e execute o seguinte comando, que vai acionar a exclusão da implantação do Agent Engine.

Verifique se você está atualizando "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)

No Cloud Shell, exclua os componentes do 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. Parabéns

Parabéns! Você configurou e validou o Agent Engine implantado com a interface do Private Service Connect e a saída da Internet realizada por um proxy explícito.

Você criou a infraestrutura do consumidor e adicionou um anexo de rede que permitiu ao produtor criar uma VM de várias NICs para fazer a ponte entre a comunicação do consumidor e do produtor. Você aprendeu a criar um proxy explícito e um peering de DNS que permitiram a conectividade com a Internet.

O Cosmopup acha que os tutoriais são incríveis!

e6d3675ca7c6911f.jpeg

Qual é a próxima etapa?

Leituras e vídeos complementares

Documentos de referência