Ruch wychodzący z bramy agenta ze środowiska wykonawczego agentów do sieci VPC

1. Wprowadzenie

W tym ćwiczeniu dowiesz się, jak zarządzać ruchem wychodzącym Agent Gateway w przypadku agentów AI uzyskujących dostęp do zdalnych punktów końcowych za pomocą prywatnej sieci VPC. Brama agenta działająca w trybie ruchu wychodzącego (agent-to-anywhere) obsługuje połączenia prywatne z siecią VPC za pomocą interfejsów Private Service Connect (PSC). W tym scenariuszu środowisko wykonawcze agenta używa bramy agenta do uzyskiwania dostępu do zdalnego serwera HTTP MCP z możliwością przesyłania strumieniowego hostowanego w Cloud Run przy użyciu punktu końcowego Private Service Connect (PSC) dla interfejsów API Google w sieci VPC.

Aplikacje AI, od samodzielnych chatbotów po autonomiczne systemy z wieloagentowymi przepływami pracy, mogą dynamicznie wywoływać narzędzia zewnętrzne. Zapewnienie agentom kontrolowanego dostępu do zapytań do baz danych, pobierania treści internetowych i wykonywania działań jest niezbędne do zapewnienia bezpieczeństwa i wydajności agentów. W środowiskach firmowych zabezpieczenie wykonywania narzędzi agenta jest jednak trudne. Jeśli agent ma bezpośredni dostęp do sieci, ataki polegające na wstrzykiwaniu promptów lub halucynacje modelu mogą spowodować, że agent wykradnie dane wrażliwe lub wykona destrukcyjne polecenia.

Aby zarządzać agentami autonomicznymi na dużą skalę, brama agentów udostępnia scentralizowany punkt egzekwowania zasad typu „zero zaufania” zintegrowany bezpośrednio z architekturą platformy agentów. Zamiast polegać na niestandardowych implementacjach unikalnych dla każdej aplikacji lub kodu agenta, Agent Gateway zapewnia routing sieciowy, zarządzanie agentami i bezpieczeństwo środowiska wykonawczego egzekwowane na poziomie platformy.

Gdy brama agenta działa w trybie wychodzącym (agent-to-anywhere), przekazuje wszystkie żądania wychodzące od agentów skonfigurowanych do korzystania z niej. Każde żądanie obciążenia agenta jest uwierzytelniane za pomocą unikalnego identyfikatora agenta i autoryzowane za pomocą zasad serwera proxy identyfikującego tożsamość (IAP). Wywołania narzędzia MCP są dynamicznie dekodowane i sprawdzane pod kątem egzekwowania zasad. Administratorzy zabezpieczeń mogą centralnie egzekwować szczegółowe uprawnienia, aby mieć pewność, że agenci mogą wywoływać tylko zatwierdzone punkty końcowe i metody.

Co utworzysz

  • Brama agentów w trybie ruchu wychodzącego (od agenta do dowolnego miejsca)
  • Rozszerzenie autoryzacji Identity-Aware Proxy (IAP)
  • Agent ADK środowiska wykonawczego agentów z tożsamością agenta
  • Serwer MCP HTTP z możliwością przesyłania strumieniowego w Cloud Run
  • Rejestr agentów z interfejsem API Google i niestandardowymi punktami końcowymi MCP
  • Zasady autoryzacji z kontrolą dostępu za pomocą uprawnień
  • Zasoby sieci VPC, strefa Cloud DNS i punkt końcowy PSC dla interfejsów API Google
  • Przyłącze sieci PSC na potrzeby ruchu wychodzącego z bramy agentów
  • Reguły zasad zapory sieciowej Cloud Next Generation Firewall (NGFW)

figure1

Rys. 1. Architektura ćwiczeń z programowania

Czego się dowiesz

  • Jak wdrożyć bramę agentów w uporządkowanej sekwencji konfiguracji
  • Konfigurowanie bramy agenta z połączeniem z prywatną siecią VPC
  • Jak przejść z trybu próbnego na tryb egzekwowania zasad autoryzacji
  • Rejestrowanie punktów końcowych interfejsu Google API i serwerów MCP w rejestrze agentów
  • Jak sprawdzać dzienniki bramy agenta, aby weryfikować zarządzanie ruchem wychodzącym
  • Jak weryfikować ruch wychodzący z bramy agenta za pomocą logów Cloud NGFW

Wymagania

  • projekt Google Cloud z włączonymi płatnościami;
  • uprawnienia IAM do udostępniania usług sieciowych, zbiorów danych BigQuery i zasobów platformy Agent Platform;
  • Powłoka zgodna z POSIX (bash lub zsh) z zainstalowanym interfejsem Google Cloud CLI (komponenty gcloud i bq).
  • Narzędzia wiersza poleceń: git, curl, jq (procesor JSON), Python 3 i uv (menedżer pakietów Pythona)

2. Pojęcia

Sekwencja wdrażania

To ćwiczenie zawiera uporządkowaną sekwencję konfiguracji, dzięki czemu agenci mają dostęp do niezbędnych zasobów podczas inicjowania, a połączenie można potwierdzić przed zastosowaniem wymuszonych zasad dostępu.

W tym laboratorium używamy tej sekwencji wdrażania:

  1. Rozpocznij w trybie DRY_RUN: sprawdź, czy żądania agenta docierają do bramy i przechodzą przez nią (tylko tryb audytu).
  2. Zarejestruj wszystkie usługi: zarejestruj wszystkie komponenty agenta w rejestrze agentów i potwierdź dostęp do narzędzi agenta. Aby wyświetlać zapytania do rejestru agentów, użyj Cloud Logging i panelu dostrzegalności bramy agentów.
  3. Tworzenie zasad autoryzacji: utwórz i zastosuj zasady autoryzacji, aby zezwolić na ruch wychodzący z agentów do serwerów i punktów końcowych MCP.
  4. Przełącz na tryb ENFORCED: zaktualizuj zasadę rozszerzenia autoryzacji, aby egzekwować zasady i blokować nieautoryzowany ruch wychodzący.

figure2

Rys. 2. Sekwencja wdrażania

Topologia routingu ruchu wychodzącego

Ruch wychodzący z bramy agenta (od agenta do dowolnego miejsca) działa jako scentralizowany wychodzący serwer proxy typu „zero zaufania” dla zadań agentowych. Gdy agent wysyła żądanie do zewnętrznego narzędzia lub interfejsu API, żądanie wychodzące jest przechwytywane przez bramę agenta i oceniane pod kątem zgodności z zasadami zarządzania przed przekierowaniem do miejsca docelowego. W architekturze platformy agentów Google Cloud brama agentów zapewnia łączność platformy danych z:

  • Sieci prywatne (VPC): ruch wychodzący kierowany do wewnętrznych interfejsów API przedsiębiorstwa, mikrousług i baz danych hostowanych w prywatnych sieciach VPC oraz sieci lokalnych lub między chmurami, do których można dotrzeć za pomocą połączenia hybrydowego.
  • Sieci zewnętrzne (internet): ruch wychodzący kierowany do usług internetowych innych firm, interfejsów API SaaS lub publicznych punktów końcowych.
  • Usługi AI i Agent Platform: ruch wychodzący kierowany do zarządzanych interfejsów API Google Cloud, modeli podstawowych, punktów końcowych Google MCP (np. BigQuery) i usług zarządzania platformą (Agent Registry i zasady IAP).

figure3

Ilustracja 3. Topologia kierowania ruchu wychodzącego przez bramę agentów

To ćwiczenie skupia się na ruchu wychodzącym z agenta niestandardowego w środowisku wykonawczym agenta, który jest kierowany do punktu końcowego PSC dla interfejsów API Google wdrożonego w sieci VPC. Ta architektura umożliwia prywatny dostęp do serwera MCP hostowanego w Cloud Run przy użyciu przyłącza sieci PSC na potrzeby ruchu wychodzącego z bramy agenta.

Połączenia VPC

Ruch wychodzący z bramy agenta (agent-to-anywhere) może łączyć się z siecią VPC, jeśli w pliku konfiguracyjnym YAML wdrożenia określono networkConfig: egress: networkAttachment: [URI]. To ustawienie konfiguruje reguły routingu w bramie agenta, aby wysyłać ruch, który jest rozpoznawany jako prywatne adresy IP, przez załącznik sieci PSC do sieci VPC.

figure4

Rys. 4. Połączenia VPC usługi bramy agentów

Brama agentów może rozpoznawać prywatne nazwy hostów DNS za pomocą połączenia równorzędnego Cloud DNS z określonym projektem docelowym i siecią VPC. Wszystkie strefy prywatne wymienione w konfiguracji dnsPeeringConfig: domains: [NAME] będą używać rekordów Cloud DNS w projekcie docelowym. W przypadku innych zapytań DNS będzie używany domyślny publiczny resolver DNS Cloud w sieci VPC.

To koniec części poświęconej pojęciom. Przejdźmy teraz do sekcji Konfiguracja.

3. Konfiguracja

Wymagane role uprawnień

Aby utworzyć zasoby w tym ćwiczeniu, musisz mieć te role:

Kategoria

Wymagana rola uprawnień (identyfikator)

Opis

Zarządzanie interfejsami API

roles/serviceusage.serviceUsageAdmin

Włączanie usług interfejsu Google Cloud API

Sieć i brama

roles/networkservices.admin

Aprowizowanie bramy agenta

Rozszerzenia usług

roles/serviceextensions.admin

Konfigurowanie rozszerzeń routingu

Bezpieczeństwo sieciowe

roles/networksecurity.admin

Wdrażanie zasad autoryzacji

Rejestr agentów

roles/agentregistry.admin

Dozwolone hosty katalogu

Vertex AI i agenty

roles/aiplatform.admin

Wdrażanie zadań środowiska wykonawczego agentów

Zasady ruchu wychodzącego

roles/iap.admin

Stosowanie zasad roles/iap.egressor

Cloud Storage

roles/storage.admin

Zarządzanie zasobnikami przejściowymi wdrożenia

Logi i audyt

roles/logging.viewer

Sprawdzanie śladów i dzienników kontrolnych

Programista Cloud Run

roles/run.developer

Wdrażanie usług Cloud Run

Odczytujący Artifact Registry

roles/artifactregistry.reader

Pobieranie obrazów kontenerów

Administrator sieci Compute

roles/compute.networkAdmin

Zarządzanie zasobami sieci VPC

Administrator DNS

roles/dns.admin

Zarządzanie strefami i rekordami Cloud DNS

Możesz też użyć szerokiej roli podstawowej, np. roles/admin, lub starszej roli roles/owner.

Dostęp do projektu

To ćwiczenie korzysta z jednego projektu Google Cloud. Kroki konfiguracji wykorzystują interfejs wiersza poleceń gcloud i polecenia powłoki Linux.

Zacznij od uzyskania dostępu do wiersza poleceń projektu Google Cloud:

Ustawianie identyfikatora projektu

gcloud config set project SET_YOUR_PROJECT_ID_HERE

Uwierzytelnianie sesji

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

Ustawianie zmiennych środowiskowych powłoki

# set custom var for slug (eg, "foo") and region preference
export SLUG="foo"
export REGION="us-central1"
export MREGION="us"
echo ${SLUG}
echo ${REGION}
echo ${MREGION}

# create project vars (automatic)
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
export USER_IDENTITY=$(gcloud config get-value account)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}
echo ${USER_IDENTITY}

# create resource vars (automatic)
export AGW_NAME="agw-${SLUG}-${REGION}-ata"
export AGW_URI="projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
export RE_AGENT_NAME="agent-weather"
export RE_AGENT_ID_SET="principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJ_NO}"
export STAGING_BUCKET="agent-staging-${PROJ_NO}"
export MCP_NAME="mcp-weather"
export MCP_DISPLAY_NAME="${MCP_NAME}-${PROJ_NO}.${REGION}.run.app"
export MCP_URL="https://${MCP_DISPLAY_NAME}/mcp"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}
echo ${MCP_NAME}
echo ${MCP_DISPLAY_NAME}
echo ${MCP_URL}

# create local dir for config files
mkdir -p cfg

Jeśli korzystasz z samodzielnie zarządzanej instalacji pakietu Google Cloud SDK (czyli poza Cloud Shell), zaktualizuj komponenty do najnowszej wersji.

# update gcloud cli
gcloud components update

Włączanie usług API

# enable google apis (agent platform bundle, part 1)
gcloud services enable \
  agentregistry.googleapis.com \
  aiplatform.googleapis.com \
  apphub.googleapis.com \
  apptopology.googleapis.com \
  cloudapiregistry.googleapis.com \
  cloudtrace.googleapis.com \
  compute.googleapis.com \
  dataform.googleapis.com \
  iam.googleapis.com \
  iamconnectors.googleapis.com \
  iap.googleapis.com \
  logging.googleapis.com \
  modelarmor.googleapis.com \
  monitoring.googleapis.com \
  networksecurity.googleapis.com \
  networkservices.googleapis.com \
  notebooks.googleapis.com \
  observability.googleapis.com

# enable google apis (agent platform bundle, part 2)
gcloud services enable \
  securitycenter.googleapis.com \
  saasservicemgmt.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com

# enable google apis (all the rest)
gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  dns.googleapis.com

To kończy część dotyczącą konfiguracji. Przejdź do sekcji Sieć.

4. Sieć

Sieć VPC jest wdrażana w trybie niestandardowym, aby utworzyć zwykłe podsieci obsługujące załącznik sieciowy PSC dla bramy agenta i bezpośredniego ruchu wychodzącego VPC w Cloud Run.

Punkt końcowy PSC dla interfejsów API Google jest wdrażany przy użyciu jednego /32globalnego wewnętrznego adresu IPv4, aby obsługiwać prywatny dostęp wewnętrzny do Cloud Run. Ten adres IP nie jest przypisany z żadnej podsieci regionalnej.

Tworzenie sieci

Utwórz globalną sieć VPC.

# create vpc network
gcloud compute networks create vnet-${SLUG} --subnet-mode=custom

Utwórz podsieci dla przyłącza sieci PSC bramy agenta i bezpośredniego ruchu wychodzącego VPC Cloud Run.

# create subnet for agent gateway psc na
gcloud compute networks subnets create subnet-${REGION}-agw \
  --network=vnet-${SLUG} \
  --range=192.168.10.0/28 \
  --region=${REGION} \
  --enable-private-ip-google-access

# create subnet for cloud run dvpc egress
gcloud compute networks subnets create subnet-${REGION}-crun \
  --network=vnet-${SLUG} \
  --range=10.10.10.0/24 \
  --region=${REGION} \
  --enable-private-ip-google-access

Utwórz reguły zapory sieciowej

Utwórz zasadę zapory sieciowej i regułę, które zezwalają na cały ruch wychodzący z włączonym logowaniem. Będzie ona służyć do monitorowania ruchu wychodzącego z bramy agenta do sieci VPC.

# create fw policy
gcloud compute network-firewall-policies create fw-policy-${SLUG} --global

# create fw policy rule
gcloud compute network-firewall-policies rules create 1001 \
  --description="allow all out and log" \
  --firewall-policy=fw-policy-${SLUG} \
  --global-firewall-policy \
  --action=allow \
  --direction=EGRESS \
  --layer4-configs=all \
  --dest-ip-ranges=0.0.0.0/0 \
  --enable-logging

# associate fw policy to vpc network
gcloud compute network-firewall-policies associations create \
  --name=fw-policy-bind-${SLUG} \
  --firewall-policy=fw-policy-${SLUG} \
  --network=vnet-${SLUG} \
  --global-firewall-policy

Tworzenie przyłącza sieci PSC

Utwórz przyłącze sieci PSC skonfigurowane tak, aby automatycznie akceptować nowe połączenia z producentem.

# create psc network attachment
gcloud compute network-attachments create psc-na-${REGION}-agw \
  --region=${REGION} \
  --subnets=subnet-${REGION}-agw \
  --connection-preference=ACCEPT_AUTOMATIC

Weryfikowanie przyłącza sieci PSC

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw --region=${REGION}

# fetch psc na uri
export PSC_NA_URI=$(gcloud compute network-attachments describe psc-na-${REGION}-agw \
  --region=${REGION} \
  --format="value(selfLink.scope(v1))")
echo ${PSC_NA_URI}

Tworzenie punktu końcowego PSC

Utwórz rezerwację adresu IP dla globalnego punktu końcowego PSC. Adres użyty w tym miejscu nie może pochodzić z istniejącej podsieci ani się z nią pokrywać.

# set env var for psc ep ip address
export PSC_EP_IP="240.0.0.10"
echo ${PSC_EP_IP}

# reserve internal global ipv4 address
gcloud compute addresses create ip-psc2gapis \
  --global \
  --purpose=PRIVATE_SERVICE_CONNECT \
  --addresses=${PSC_EP_IP} \
  --network=vnet-${SLUG}

Utwórz punkt końcowy PSC dla interfejsów API Google za pomocą pakietu all-apis, który obejmuje Cloud Run (run.app).

# create psc endpoint for google apis
gcloud compute forwarding-rules create psc2gapis \
  --global \
  --network=vnet-${SLUG} \
  --address=ip-psc2gapis \
  --target-google-apis-bundle=all-apis

Weryfikowanie punktu końcowego PSC

# show psc endpoint details
gcloud compute forwarding-rules describe psc2gapis --global

Tworzenie strefy i rekordów DNS

Utwórz prywatną zarządzaną strefę Cloud DNS dla domeny run.app.

# create private dns zone
gcloud dns managed-zones create priv-zone-run \
  --description="private zone for cloud run" \
  --dns-name="run.app." \
  --visibility=private \
  --networks=vnet-${SLUG}

Utwórz rekord DNS z symbolem wieloznacznym A dla *.run.app., który będzie wskazywać adres IP punktu końcowego PSC.

# create dns record
gcloud dns record-sets create *.run.app \
  --zone=priv-zone-run \
  --type=A \
  --ttl=300 \
  --rrdatas=${PSC_EP_IP}

Utwórz zasadę Cloud DNS, aby włączyć logowanie zapytań DNS.

# create dns policy (logging)
gcloud dns policies create dns-policy-${SLUG} \
  --description="dns logging for vnet-${SLUG}" \
  --networks=vnet-${SLUG} \
  --enable-logging

Tworzenie Cloud NAT

Utwórz Cloud Router i Cloud NAT, aby obsługiwać bezpośredni ruch wychodzący VPC w Cloud Run, dzięki czemu serwer MCP będzie mógł uzyskiwać dostęp do zewnętrznych danych pogodowych przez sieć VPC.

# create router for nat
gcloud compute routers create cr-nat-${SLUG}-${REGION} \
  --network=vnet-${SLUG} \
  --asn=16550 \
  --region=${REGION}

# create nat gateway
gcloud compute routers nats create nat-${SLUG}-${REGION} \
  --router=cr-nat-${SLUG}-${REGION} \
  --region=${REGION} \
  --auto-allocate-nat-external-ips \
  --nat-all-subnet-ip-ranges

To koniec części dotyczącej sieci. Przejdźmy teraz do sekcji Brama.

5. Brama

Przed wymuszeniem kontroli dostępu wdróż bramę agentów i skonfiguruj rozszerzenie autoryzacji w trybie DRY_RUN. Umożliwia to pomyślne wykonanie wywołań narzędzi wychodzących przy jednoczesnym rejestrowaniu wyników oceny na potrzeby kontroli.

W tym przypadku brama agentów używa rejestru regionalnego do obsługi zasobów środowiska wykonawczego agenta regionalnego i określa pola networkConfig dla przyłącza sieci PSC sieci VPC i konfiguracji połączenia równorzędnego DNS.

Utwórz bramę

# create new agent gateway config file (with network settings)
cat > cfg/${AGW_NAME}-networkConfig.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
networkConfig:
  egress:
    networkAttachment: ${PSC_NA_URI}
  dnsPeeringConfig:
    domains:
      - run.app.
    targetProject: ${PROJ_ID}
    targetNetwork: projects/${PROJ_ID}/global/networks/vnet-${SLUG}
EOF

# import agent gateway config file (create gateway)
gcloud network-services agent-gateways import ${AGW_NAME} \
  --source="cfg/${AGW_NAME}-networkConfig.yaml" \
  --location=${REGION}

Weryfikacja bramy

# show agent gateway details
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw --region=${REGION}

Sprawdź, czy istnieje zaakceptowany punkt końcowy połączenia.

connectionEndpoints:
- ipAddress: 192.168.10.2
  projectIdOrNum: '[AGW_PROJECT_NO]'
  status: ACCEPTED
  subnetwork: https://www.googleapis.com/compute/v1/projects/${PROJ_ID}/regions/${REGION}/subnetworks/subnet-${REGION}-agw

To kończy część dotyczącą bramy. Przejdźmy teraz do sekcji Autoryzacja.

6. Autoryzacja

Rozszerzenie autoryzacji bramy agentów dla Identity-Aware Proxy (IAP) to rodzaj rozszerzenia usługi, które służy do delegowania decyzji o autoryzacji w przypadku całej komunikacji platformy agentów.

  1. Przepływ delegowania: gdy agent próbuje wywołać zewnętrzny punkt końcowy lub serwer MCP, kieruje żądanie do bramy agenta. Zamiast oceniać dostęp lokalnie, brama używa rozszerzenia autoryzacji, aby wysłać wywołanie do usługi oceny IAP. IAP ocenia tożsamość agenta (opartą na SPIFFE) pod kątem zasad IAM zasobu docelowego w rejestrze agentów. IAP zwraca do bramy decyzję ALLOW lub DENY, która przekazuje ruch dalej lub blokuje go za pomocą kodu stanu HTTP 403 Forbidden.
  2. Tryby egzekwowania: w trybie DRY_RUN IAP ocenia żądania i rejestruje decyzje w Cloud Logging bez blokowania ruchu. W trybie ENFORCE każde żądanie od nieautoryzowanego agenta lub do niezarejestrowanego miejsca docelowego jest natychmiast blokowane.
  3. Warstwa powiązań: rozszerzenie usługi jest połączone z bramą agentów za pomocą zasady autoryzacji skonfigurowanej z profilem REQUEST_AUTHZ.

Rozszerzenie autoryzacji

Rozszerzenie autoryzacji określa usługę dostawcy zabezpieczeń z ustawieniami połączenia i innymi parametrami, które definiują sposób działania usługi i jej integracji z bramą agenta.

Tworzenie rozszerzenia autoryzacji

# create authz extension config file (dry run mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-dryrun
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iamEnforcementMode: "DRY_RUN"
  iapPolicyVersion: "V1"
EOF

Importowanie rozszerzenia autoryzacji

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml \
  --location=${REGION}

Weryfikowanie rozszerzenia autoryzacji

# show authz extension details
gcloud service-extensions authz-extensions describe ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --location=${REGION}

Zasady dotyczące upoważnienia

Zasady autoryzacji wiążą dostawcę zabezpieczeń (IAP) z docelowym zasobem bramy i określają profil przechwytywania (REQUEST_AUTHZ).

Tworzenie zasady autoryzacji

# create authz policy config file (attach dry-run authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-dryrun"
EOF

Powiązywanie zasady autoryzowania

# import authz policy config file (enable authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

Sprawdzanie zasady autoryzowania

# show authz policy details
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

To kończy część dotyczącą autoryzacji. Przejdźmy teraz do sekcji Baza kodu.

7. Baza kodu

Kod agenta, serwera MCP i rejestracji punktu końcowego użyty w tym ćwiczeniu jest przechowywany w zdalnym repozytorium Google Cloud na GitHubie. W ramach tych czynności repozytorium zostanie sklonowane lokalnie, niezbędne pliki zostaną skopiowane do bieżącej struktury katalogów roboczych, a następnie pliki tymczasowe zostaną usunięte.

Tworzony jest zasobnik tymczasowy na dane, do którego środowisko wykonawcze agentów przesyła, kompiluje i wdraża spakowany kod aplikacji agenta oraz artefakty zależności.

Pobieranie artefaktów zdalnych

# clone remote repository to temp local dir
git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git ./temp_agw_cuj_arun_egress_vpc

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_vpc/codelabs/agw-cuj-arun-egress-vpc/agent-weather ./agent-weather
cp -r temp_agw_cuj_arun_egress_vpc/codelabs/agw-cuj-arun-egress-vpc/mcp-weather ./mcp-weather

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_vpc

Tworzenie zasobnika testowego

# create storage bucket for agent deployment artifacts
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}

# verify staging bucket url
gcloud storage buckets list --format="value(storage_url)"

To koniec części dotyczącej bazy kodu. Przejdźmy teraz do sekcji Rejestr.

8. Rejestr

Rejestr agentów to scentralizowany spis wszystkich agentów, serwerów MCP i punktów końcowych (interfejsów API) w ekosystemie AI. Jest to też katalog, w którym można wyświetlać, wyszukiwać i odkrywać inne zarejestrowane narzędzia i usługi do wykorzystania w aplikacjach AI. Brama agentów używa modelu danych rejestru jako platformy zarządzania do egzekwowania kontroli dostępu wychodzącego. Uprawnienia do roli IAM dla agentów wywołujących podmiot zabezpieczeń są sprawdzane na podstawie zasad powiązanych z zasobem rejestru.

Aby uruchomić środowisko i obsługiwać agenta za pomocą różnych interfejsów API i usług Google, utwórz pojedynczą usługę punktu końcowego rejestru, która zawiera podstawowe interfejsy API potrzebne w tym ćwiczeniu. Ułatwi to zarządzanie zasadami dotyczącymi wspólnych zestawów narzędzi, z których korzysta większość agentów.

Rejestrowanie punktów końcowych

# create endpoint service (with multiple entries)
gcloud agent-registry services create core-gapi-services \
  --location=${REGION} \
  --display-name="gapi.core.services" \
  --description="core apis and services" \
  --endpoint-spec-type=no-spec \
  --interfaces=protocolBinding=JSONRPC,url=https://telemetry.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://${REGION}-aiplatform.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://cloudresourcemanager.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://iamcredentials.googleapis.com

Weryfikowanie rejestracji punktu końcowego

# list registry regional endpoints
gcloud agent-registry endpoints list --location=${REGION} \
  --flatten="interfaces[]" \
  --format="table(displayName, name.basename():label=ENDPOINT_ID, interfaces.url:label=URL)"

To wszystko, jeśli chodzi o rejestr. Przejdźmy teraz do sekcji serwera MCP.

9. Serwer MCP

Przyznawanie uprawnień do wdrażania

Przyznaj domyślnemu kontu usługi Compute uprawnienia do wdrażania usług Cloud Run z kodu źródłowego.

# grant cloud run builder role to default compute sa
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

Sprawdzanie uprawnień

# show iam policy on project for default compute sa
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members=serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

Wdrażanie serwera MCP

# deploy cloud run service
gcloud -q run deploy ${MCP_NAME} \
  --source=mcp-weather/server \
  --region=${REGION} \
  --no-allow-unauthenticated \
  --min-instances=1 \
  --network=vnet-${SLUG} \
  --subnet=subnet-${REGION}-crun \
  --vpc-egress=all-traffic \
  --startup-probe=httpGet.path=/warmup

Przyznawanie uprawnień do ruchu przychodzącego

Powiązywanie zasad dostępu użytkownika

Przyznaj uprawnienia do wywoływania hostowanego serwera MCP w Cloud Run na koncie użytkownika (własnym). Jest to wymagane do uruchomienia skryptu generowania toolspec.

# grant run invoker role to user account on cloud run service level
gcloud run services add-iam-policy-binding ${MCP_NAME} \
  --region=${REGION} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/run.invoker"

Sprawdzanie uprawnień

# show iam policy on cloud run service for invoker role
gcloud run services get-iam-policy ${MCP_NAME} \
  --region=${REGION} \
  --flatten="bindings[].members" \
  --filter="bindings.role=roles/run.invoker" \
  --format="table(bindings.members:label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Tworzenie niestandardowego konta usługi na potrzeby wywoływania MCP

Utwórz niestandardowe konto usługi do wywoływania hostowanego serwera MCP Cloud Run. To konto usługi będzie używane przez agenta do pobierania ważnego tokena identyfikatora OIDC podpisanego przez Google, aby uzyskać dostęp do Cloud Run.

# create custom sa for mcp server invocation
gcloud iam service-accounts create sa-${MCP_NAME}-invoker \
  --display-name="custom sa to invoke ${MCP_NAME}"

# set env var for service account identity
export MCP_INVOKER_SA="sa-${MCP_NAME}-invoker@${PROJ_ID}.iam.gserviceaccount.com"
echo ${MCP_INVOKER_SA}

Zasada wiązania konta usługi

# grant run invoker role to custom sa on cloud run service level
gcloud run services add-iam-policy-binding ${MCP_NAME} \
  --role="roles/run.invoker" \
  --member="serviceAccount:${MCP_INVOKER_SA}" \
  --region=${REGION}

Sprawdzanie uprawnień

# show iam policy on cloud run service for invoker role
gcloud run services get-iam-policy ${MCP_NAME} \
  --region=${REGION} \
  --flatten="bindings[].members" \
  --filter="bindings.role=roles/run.invoker" \
  --format="table(bindings.members:label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Przyznawanie uprawnień na potrzeby uwierzytelniania

Przyznaj domyślnemu kontu usługi Compute role przyjmującego tożsamość konta usługi. Umożliwi to agentowi działającemu w ramach domyślnych danych logowania aplikacji (ADC) generowanie podpisanych przez Google tokenów tożsamości OIDC w imieniu niestandardowego konta usługi wywołującej w celu uwierzytelniania wywołań Cloud Run.

Powiązywanie zasady z uwierzytelnianiem

# grant oidc token creator role to default compute service account
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountOpenIdTokenCreator" \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com"

# grant service account token creator role to default compute service account
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountTokenCreator" \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com"

Sprawdzanie uprawnień

# show iam policy for the custom service account
gcloud iam service-accounts get-iam-policy ${MCP_INVOKER_SA} \
  --flatten="bindings[].members" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

Utwórz MCP toolspec

Podczas ręcznego rejestrowania serwera MCP należy dołączyć plik specyfikacji narzędzia. toolspec.json zawiera listę wszystkich narzędzi udostępnianych przez serwer MCP i umożliwia innym użytkownikom ich odkrywanie po zarejestrowaniu.

Skrypt test_mcp.py, który jest częścią mcp-weather/ bazy kodu, generuje plik toolspec.json, łącząc się z docelowym serwerem MCP (przez SSE lub HTTP) i wywołując funkcję list_tools() w celu pobrania wszystkich dostępnych narzędzi udostępnianych przez serwer.

# fetch oidc token for cloud run authentication
export OIDC_TOKEN=$(gcloud auth print-identity-token)

# generate toolspec for registry ingestion
uv --directory mcp-weather run test_mcp.py --toolspec=include --token="${OIDC_TOKEN}"

Wygenerowane dane wyjściowe toolspec pokazują atrybuty MCP, których brama agentów może używać do oceny i egzekwowania zasad wychodzących.

Weryfikacja MCP toolspec

# show toolspec mcp attributes
jq '.tools[] | {name, isReadOnly, isDestructive, isIdempotent, isOpenWorld}' mcp-weather/toolspec.json

Aktualizowanie ruchu przychodzącego do Cloud Run

Zmień ustawienie ruchu przychodzącego dla usługi Cloud Run, aby akceptowała tylko żądania przychodzące z sieci VPC. Uniemożliwia to bezpośredni dostęp publiczny do punktu końcowego MCP i zezwala na dostęp do niego tylko zasobom wewnętrznym. Ruch przeznaczony dla punktu końcowego PSC interfejsów API Google w sieci VPC będzie traktowany jako wewnętrzny ruch przychodzący i będzie dozwolony.

# update cloud run service config
gcloud run services update ${MCP_NAME} \
  --region=${REGION} \
  --ingress=internal

Sprawdzanie ruchu przychodzącego do Cloud Run

# show cloud run service details
gcloud run services describe ${MCP_NAME} --region=${REGION} | grep -iE 'ingress|egress'

Rejestrowanie serwera MCP

Teraz, gdy masz toolspec, zarejestruj serwer MCP w regionalnym rejestrze agentów.

# register mcp server
gcloud agent-registry services create ${MCP_NAME} \
  --location=${REGION} \
  --display-name="${MCP_DISPLAY_NAME}" \
  --description="mcp server for weather info" \
  --mcp-server-spec-type=tool-spec \
  --mcp-server-spec-content=mcp-weather/toolspec.json \
  --interfaces=url=${MCP_URL},protocolBinding=JSONRPC

Weryfikowanie rejestracji w programie MCP

# list registry regional mcp servers
gcloud agent-registry mcp-servers list --location=${REGION} --format="table(displayName, interfaces.url)"

# show mcp server registry details
gcloud agent-registry services describe ${MCP_NAME} --location=${REGION}

# fetch mcp server registry id
export MCP_REGISTRY_ID=$(gcloud agent-registry services describe ${MCP_NAME} \
  --location=${REGION} \
  --format="value(registryResource.basename())")
echo ${MCP_REGISTRY_ID}

To koniec sekcji poświęconej serwerowi MCP. Przejdźmy teraz do sekcji agenta pakietu ADK.

10. Agent ADK

agent-weather Agent ADK wdrożony w środowisku wykonawczym agenta jest skonfigurowany w skrypcie wdrażania z tymi ustawieniami, aby zintegrować się z platformą agenta:

  • "identity_type": types.IdentityType.AGENT_IDENTITY udostępnić agentowi unikalną tożsamość podmiotu zabezpieczeń opartą na SPIFFE,
  • "agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } }, aby kierować cały ruch wychodzący inicjowany przez agenta do bramy agenta w celu oceny i egzekwowania zasad.

Agent jest też skonfigurowany do korzystania z serwera MCP przez przekazywanie adresu URL i konta usługi w celu pobrania tokena identyfikatora OIDC.

Wdrażanie agenta

# deploy agent runtime workload
uv --directory agent-weather run python3 deploy_agent.py \
  --project=${PROJ_ID} \
  --region=${REGION} \
  --src-dir=./agent \
  --staging-bucket=${STAGING_BUCKET} \
  --display-name="${RE_AGENT_NAME}" \
  --description="agent for weather info" \
  --mcp-server-url="${MCP_URL}" \
  --mcp-invoker-sa="${MCP_INVOKER_SA}" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --allow-token-sharing

Sprawdzanie wdrożenia

Pobieranie parametrów życiowych wdrożenia

# fetch agent runtime resource (reasoning engine) id
export RE_ENGINE_ID=$(curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" | \
  jq -r --arg name "${RE_AGENT_NAME}" '.reasoningEngines[] | select(.displayName==$name) | .name | split("/") | last')
echo ${RE_ENGINE_ID}

# fetch agent runtime (reasoning engine) agent identity
export RE_AGENT_IDENTITY=$(gcloud agent-registry agents list \
  --location=${REGION} --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(attributes.'agentregistry.googleapis.com/system/RuntimeIdentity'.principal)")
echo ${RE_AGENT_IDENTITY}

# fetch agent registry uid for agent
export RE_AGENT_REGISTRY_ID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${RE_AGENT_REGISTRY_ID}

Weryfikowanie wpisu w rejestrze

# show agent resource registry details
gcloud agent-registry agents describe ${RE_AGENT_REGISTRY_ID} --location=${REGION}

Sprawdzanie konfiguracji bramy

# show agent config details (gateway config)
curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  | jq '{displayName: .displayName, name: .name, effectiveIdentity: .spec.effectiveIdentity, agentGatewayConfig: .spec.deploymentSpec.agentGatewayConfig}'

Przyznawanie uprawnień na potrzeby uwierzytelniania

Gdy agent jest skonfigurowany do korzystania z tożsamości agenta, otrzymuje token (w formacie JWT-SVID) z federacyjnej usługi tokenów bezpieczeństwa (STS), który jest podpisany przez sts.googleapis.com (dostawcę tożsamości SPIFFE).

Wbudowana w Cloud Run funkcja sprawdzania uprawnień wywołującego IAM ufa jednak tylko standardowym tokenom tożsamości OIDC podpisanym przez głównego wystawcę OIDC Google (accounts.google.com) i może je weryfikować.

Dlatego niestandardowe konto usługi jest używane do wymiany tokena federacyjnego STS (JWT-SVID) uzyskanego przez tożsamość agenta na standardowy token Google (OIDC) uzyskany za pomocą podszywania się pod konto usługi w czasie działania.

Utwórz powiązania ról wymagane w przypadku niestandardowego konta usługi.

Powiązywanie zasad uwierzytelniania (podszywania się)

# grant service account token creator role to agent principal identity
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountTokenCreator" \
  --member="${RE_AGENT_IDENTITY}"

# grant service account openid token creator role to agent principal identity
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountOpenIdTokenCreator" \
  --member="${RE_AGENT_IDENTITY}"

Sprawdzanie uprawnień

# show iam policy for custom service account
gcloud iam service-accounts get-iam-policy ${MCP_INVOKER_SA} \
  --flatten="bindings[].members" \
  --format="table(bindings.members.sub('^.*locations/', '.../locations/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Przyznawanie uprawnień w czasie działania

Przyznanie uprawnień IAM w czasie działania umożliwia agentowi dostęp do usług platformy AI i innych podstawowych interfejsów API i usług Google za pomocą opartej na SPIFFE tożsamości agenta głównego. Te zasady są egzekwowane za pomocą usługi IAM na poziomie zasobu.

Utwórz powiązania ról potrzebne do tożsamości agenta.

Powiązywanie zasad na potrzeby dostępu agenta

# grant ai platform user role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.user"

# grant agent default access role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.agentDefaultAccess"

# grant agent registry viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/agentregistry.viewer"

# grant cloud logging writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/logging.logWriter"

# grant cloud monitoring writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/monitoring.metricWriter"

# grant browser role for resource manager lookup
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/browser"

Sprawdzanie uprawnień

# show iam policy on project for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="table(bindings.members.sub('^.*locations/', '.../locations/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

To wszystko, jeśli chodzi o agenta pakietu ADK. Przejdźmy teraz do sekcji Zasady.

11. Zasady

Zasady autoryzacji zarządzania agentami zezwalają na kierowanie ruchu z agenta AI przez bramę agentów do miejsca docelowego zasobu (np. prywatnego punktu końcowego serwera MCP w celu pobierania danych). Gdy ruch dotrze do miejsca docelowego, dostęp do danych jest autoryzowany przez zwykłe uprawnienia na poziomie usługi lub aplikacji.

Przyznawanie ról IAM na potrzeby ruchu wychodzącego z bramy agentów umożliwia stosowanie zasad dostępu, które zezwalają tożsamości podmiotu zabezpieczeń agenta na dostęp do zarejestrowanych zasobów docelowych za pośrednictwem bramy agentów. Zasady są egzekwowane na poziomie bramy agentów i weryfikowane przy użyciu zasad uprawnień Identity-Aware Proxy (IAP).

Przyznawanie ról uprawnień na potrzeby wychodzącego ruchu z bramy agenta

Brama agentów sprawdza przychodzące żądania, aby potwierdzić, że tożsamość agenta wywołującego ma uprawnienie iap.webServiceVersions.egressViaIAP (przyznane przez rolę roles/iap.egressor) w zasobie docelowym.

Przyznanie roles/iap.egressor tożsamości agenta lub zbiorowi podmiotów zabezpieczeń środowiska wykonawczego agenta w wybranym zasobie docelowym zezwala na ten ruch wychodzący. W tym ćwiczeniu rola jest przypisywana do podmiotu zabezpieczeń agent, co przyznaje uprawnienia do konkretnej tożsamości agenta środowiska wykonawczego agentów.

Zasady IAM są powiązane z zasobami docelowymi zgodnie z modelem danych rejestru agentów. Zasób iap_web/agentRegistry reprezentuje poziom „w całym rejestrze” w hierarchii IAM. gdzie agentRegistry jest elementem nadrzędnym dla poszczególnych zasobów podrzędnych w przypadku agents, mcpServers i endpoints. W tym laboratorium kodowym zasady IAM są powiązane z poziomami mcpServer i endpoint, co powoduje zastosowanie uprawnień do konkretnych zasobów podrzędnych.

Konfigurowanie zasady agenta na serwerze MCP

Tworzenie zasady dla agenta na serwerze MCP

# fetch active etag on policy for mcp server
export IAP_ETAG=$(gcloud beta iap web get-iam-policy \
  --resource-type=agent-registry --region=${REGION} \
  --mcp-server=${MCP_REGISTRY_ID} --format="value(etag)")
echo ${IAP_ETAG}

UWAGA: etag: powinna zwracać domyślną wartość ACAB, ponieważ nie zdefiniowano jeszcze żadnych zasad.

# create policy config file
cat > cfg/iap-policy-agent-to-mcp.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ],
  "etag": "${IAP_ETAG}"
}
EOF

Powiązywanie zasad agenta z serwerem MCP

# import policy file
gcloud beta iap web set-iam-policy cfg/iap-policy-agent-to-mcp.json \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID} \
  --region=${REGION}

Sprawdzanie uprawnień

# show iap iam policy on mcp server for agent
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID}

To koniec części dotyczącej zasad. Przejdźmy teraz do sekcji Kontrola.

12. Kontrola

Rozszerzenie autoryzacji bramy agentów działa w trybie DRY_RUN. Żądania wychodzące są obserwowane i rejestrowane, ale nie blokowane. Analiza logów przed przełączeniem na tryb ENFORCED pozwoli potwierdzić, które zasady należy skonfigurować, aby zezwolić na zamierzony ruch.

Testowanie zapytań do agenta

Otwórz okno przeglądarki z interfejsem konsoli Google Cloud i przejdź do:

  • Agent Platform → Agenty → Wdrożenia → agent-weather
  • Kliknij kartę Playground (Plac zabaw).

Możesz też wpisać to polecenie w terminalu i kliknąć link, aby przejść do piaskownicy agenta:

# playground
echo "https://console.cloud.google.com/agent-platform/runtimes/locations/${REGION}/agent-engines/${RE_ENGINE_ID}/playground?project=${PROJ_ID}"

Prześlij kilka zapytań testowych…

  • What is the weather like in London?
  • How warm is it in New York?

Sprawdź, czy zapytania zwracają prawidłowe odpowiedzi.

Analizowanie logów kontrolnych

Wyświetl logi i sprawdź oceny zasad uruchomionych próbnie.

# show gateway logs for endpoints and authz status (duplicates removed)
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=50 \
  --freshness=24h \
  --format="table( \
    timestamp.date(tz=LOCAL):label=TIMESTAMP, \
    httpRequest.status:label=STATUS, \
    jsonPayload.authzPolicyInfo.result:label=AUTHZ, \
    httpRequest.requestUrl.sub('(https?://[^/:]+).*', '\1'):label=ENDPOINT \
  )" | awk 'NR==1 {print; next} ! seen[$2,$3,$4]++'

TIMESTAMP            STATUS  AUTHZ    ENDPOINT
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://cloudresourcemanager.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://${REGION}-aiplatform.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://iamcredentials.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://mcp-weather-${PROJ_NO}.${REGION}.run.app
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://telemetry.googleapis.com
YYYY-MM-DDTHH:MM:SS  202     ALLOWED  https://mcp-weather-${PROJ_NO}.${REGION}.run.app

Konfigurowanie zasady agenta w punktach końcowych

Ponieważ podstawowe interfejsy API Google dla agent-weather zostały zarejestrowane w rejestrze w ramach zbiorczej usługi punktu końcowego (gapi.core.services), do przyznania agentowi uprawnień do wyjścia w celu uzyskania dostępu do punktu końcowego wystarczy jedna zasada.

Tworzenie zasad dotyczących agenta i punktu końcowego

# set var for endpoint display name
export ENDPOINT_DISPLAY_NAME="gapi.core.services"
echo ${ENDPOINT_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_REGISTRY_ID}

# create policy config file
cat > cfg/iap-policy-agent-to-ep.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ]
}
EOF

Powiązywanie zasady agenta z punktem końcowym

# import policy file (bind iam policy)
gcloud -q beta iap web set-iam-policy cfg/iap-policy-agent-to-ep.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID} \
  --region=${REGION}

Sprawdzanie uprawnień

# show iap iam policy on endpoint for agent
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID}

To koniec części dotyczącej audytu. Przejdźmy teraz do sekcji Wymuszanie.

13. Egzekwuj

Agentowi udało się wysłać żądania przez bramę w trybie DRY_RUN. Dzienniki dostępu i punkty końcowe zostały przeanalizowane w celu utworzenia zestawu zasad zarządzania, które zezwalają na niezbędny ruch wychodzący z agenta. Teraz przełącz rozszerzenie autoryzacji IAP bramy agenta w tryb ENFORCE, aktualizując zasadę autoryzacji.

Aktualizowanie rozszerzenia autoryzacji

Tworzenie rozszerzenia autoryzacji

# create authz extension config file (enforced mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-enforced
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V1"
EOF

Importowanie rozszerzenia autoryzacji

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-enforced \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml \
  --location=${REGION}

Weryfikowanie rozszerzenia autoryzacji

# list authz extensions (imported configs)
gcloud service-extensions authz-extensions list --location=${REGION}

Aktualizowanie zasady autoryzacji

Tworzenie zasady autoryzacji

# re-write authz policy config file (pointing to enforced authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-enforced"
EOF

Powiązywanie zasady autoryzowania

# import authz policy config file (enable new authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

Sprawdzanie zasady autoryzowania

# show authz policy details (verify enforced mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

Weryfikowanie egzekwowania

Wróć do placu zabaw agenta w interfejsie konsoli.

  • Aby utworzyć nową sesję czatu, kliknij przycisk „+ Nowa sesja”.

Prześlij dodatkowe zapytanie testowe…

  • What is the current temperature in Los Angeles?

Sprawdź, czy żądania agenta do modelu podstawowego Gemini (${REGION}-aiplatform.googleapis.com/...) i punktu końcowego serwera MCP (mcp-weather-${PROJ_NO}.${REGION}.run.app/mcp) są przekazywane z kodami stanu HTTP 200 OK.

Analizowanie logów bramy

# show gateway logs for http requests
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    httpRequest.requestUrl:label=URL)"

Sprawdź, czy żadne żądania nie są blokowane. W dziennikach kontrolnych bramy poszukaj odrzuconych prób wyjścia z kodami stanu HTTP 403 Forbidden.

# show gateway logs for authz denies
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND (jsonPayload.authzPolicyInfo.result=\"DENIED\" OR httpRequest.status=403)" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.enforcedGatewaySecurityPolicy.serverNameIndication:label=SNI,
    jsonPayload.authzPolicyInfo.result:label=AUTHZ_RESULT,
    jsonPayload.authzPolicyInfo.policies[0].name.basename():label=DENYING_POLICY
  )"

Wyświetl logi MCP bramy agenta i zwróć uwagę, jak ładunek aplikacji MCP (JSON-RPC) jest sprawdzany w celu ujawnienia metadanych protokołu, w tym informacji o tym, które narzędzia są wykonywane.

# show gateway logs for mcp requests with method and tool name
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND jsonPayload.agentGatewayInfo.mcpInfo.method:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    jsonPayload.agentGatewayInfo.mcpInfo.parameter:label=TOOL_NAME,
    httpRequest.requestUrl:label=URL
  )"

Analizowanie logów zapory sieciowej

Wyświetl logi dotyczące priorytetu reguły zasady zapory sieciowej 1001.

# show firewall logs for rule 1001
gcloud logging read \
  "jsonPayload.rule_details.priority=1001" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    jsonPayload.disposition:label=ACTION,
    jsonPayload.connection.src_ip:label=SRC_IP,
    jsonPayload.connection.dest_ip:label=DEST_IP,
    jsonPayload.connection.dest_port:label=DEST_PORT,
    jsonPayload.vpc.subnetwork_name:label=SUBNET
  )"

Zwróć uwagę na widok na poziomie sieci różnych ścieżek ruchu:

  • Brama agenta komunikująca się z zasobami wewnętrznej sieci VPC za pomocą subnet-${REGION}-agw
  • Serwer MCP hostowany w Cloud Run, który wywołuje zewnętrzne interfejsy API pogodowe za pomocą subnet-${REGION}-crun
TIMESTAMP            ACTION   SRC_IP        DEST_IP        DEST_PORT  SUBNET
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   188.40.99.226  443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   188.40.99.226  443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw

Analizowanie logów DNS

Wyświetl dzienniki zapytań DNS dotyczące żądań rozpoznanych przez prywatną strefę DNS (priv-zone-run).

gcloud logging read \
  "resource.type=\"dns_query\" AND resource.labels.target_name=\"priv-zone-run\"" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    jsonPayload.queryName:label=QUERY_NAME,
    jsonPayload.queryType:label=TYPE,
    jsonPayload.rdata:label=RESPONSE_RDATA,
    jsonPayload.sourceNetwork:label=NETWORK,
    resource.labels.source_type:label=SRC_TYPE
  )"

Uwaga: wyszukiwania DNS dla usługi Cloud Run (mcp-weather...run.app) pochodzą z sieci VPC przy użyciu połączeń równorzędnych DNS i są prawidłowo rozpoznawane jako wewnętrzny punkt końcowy PSC dla interfejsów API Google (240.0.0.10).

TIMESTAMP            QUERY_NAME                                     TYPE  RESPONSE_RDATA                                                     NETWORK   SRC_TYPE
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone

To wszystko, jeśli chodzi o wymuszanie. Przejdźmy teraz do sekcji Czyszczenie.

14. Czyszczenie 

# delete agent runtime
curl -s -X DELETE "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}?force=true" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# next

# delete agent resources
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}

for ROLE in \
  "roles/aiplatform.user" \
  "roles/aiplatform.agentDefaultAccess" \
  "roles/agentregistry.viewer" \
  "roles/logging.logWriter" \
  "roles/monitoring.metricWriter" \
  "roles/browser"; do
  gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
    --member="${RE_AGENT_IDENTITY}" \
    --role="${ROLE}"
done

# next

# delete mcp (cloud run) resources
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

gcloud -q run services delete ${MCP_NAME} --region=${REGION}

gcloud -q artifacts repositories delete cloud-run-source-deploy --location=${REGION}

gcloud -q iam service-accounts delete sa-${MCP_NAME}-invoker@${PROJ_ID}.iam.gserviceaccount.com

gcloud -q agent-registry services delete ${MCP_NAME} --location=${REGION}

# next

# delete gateway resources (policy binding must be deleted synchronously first)
gcloud -q beta network-security authz-policies delete ${AGW_NAME}-authz-policy-profile-iap --location=${REGION}

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-dryrun --location=${REGION} --async

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-enforced --location=${REGION} --async

gcloud -q network-services agent-gateways delete ${AGW_NAME} --location=${REGION} --async

# next

# remove policies
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --endpoint=${ENDPOINT_REGISTRY_ID} --region=${REGION} --format="value(etag)")
cat > cfg/iap-policy-empty.json << EOF
{
  "bindings": [],
  "etag": "${IAP_ETAG}"
}
EOF

gcloud -q beta iap web set-iam-policy cfg/iap-policy-empty.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID} \
  --region=${REGION}

# next

# delete dns resources
gcloud -q dns record-sets delete *.run.app --type=A --zone=priv-zone-run

gcloud -q dns managed-zones delete priv-zone-run

gcloud -q dns policies update dns-policy-${SLUG} --networks=""

gcloud -q dns policies delete dns-policy-${SLUG}

# next

# delete router (includes nat) and psc resources
gcloud -q compute routers delete cr-nat-${SLUG}-${REGION} --region=${REGION}

gcloud -q compute forwarding-rules delete psc2gapis --global

gcloud -q compute addresses delete ip-psc2gapis --global

# next

# delete firewall resources
gcloud -q compute network-firewall-policies associations delete --name=fw-policy-bind-${SLUG} --firewall-policy=fw-policy-${SLUG} --global-firewall-policy

gcloud -q compute network-firewall-policies rules delete 1001 --firewall-policy=fw-policy-${SLUG} --global-firewall-policy

gcloud -q compute network-firewall-policies delete fw-policy-${SLUG} --global

# next

# delete network resources
gcloud -q compute networks subnets delete subnet-${REGION}-agw --region=${REGION}

gcloud -q compute networks subnets delete subnet-${REGION}-crun --region=${REGION}

gcloud -q compute network-attachments delete psc-na-${REGION}-agw --region=${REGION}

gcloud -q compute networks delete vnet-${SLUG}

# next

# clean up local working directories and generated configs
rm -rf cfg agent-weather mcp-weather

# end

To koniec części poświęconej czyszczeniu. Przejdźmy teraz do podsumowania.

15. Podsumowanie

Gratulacje! Udało Ci się wdrożyć bramę agentów i zarządzać ruchem wychodzącym agentów AI.

cosmopup

Cosmopup uważa, że Codelabs to świetna sprawa!

Co dalej?

Jeśli masz jakieś uwagi, pytania lub poprawki, możesz je przesłać za pomocą tego formularza opinii.

Dziękujemy!