Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Ruch wychodzący bramy agentów ze środowiska Agent Runtime do Google MCP

1. Wprowadzenie

To ćwiczenie dotyczy zarządzania ruchem wychodzącym Agent Gateway w przypadku agentów AI uzyskujących dostęp do zdalnych serwerów Model Context Protocol (MCP) w Google Cloud.

Aplikacje AI, od samodzielnych chatbotów po autonomiczne systemy z przepływami pracy obejmującymi wielu agentów, 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. Jednak w środowiskach firmowych zabezpieczenie wykonywania narzędzi agenta jest 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 zapewnia scentralizowany punkt egzekwowania zasad typu „zero zaufania” zintegrowany bezpośrednio z architekturą Agent Platform. 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 agentów działa w trybie ruchu wychodzącego (agent-to-anywhere), przekazuje wszystkie żądania wychodzące od agentów skonfigurowanych do korzystania z bramy. Każde żądanie obciążenia agenta jest uwierzytelniane za pomocą unikalnego identyfikatora agenta i autoryzowane za pomocą zasad Identity-Aware Proxy (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 Runtime ADK agent z tożsamością agenta
Rejestr agentów z interfejsem Google API i punktami końcowymi MCP
Zasady autoryzacji z kontrolą dostępu za pomocą uprawnień
Zbiór danych BigQuery, o który można wysyłać zapytania za pomocą MCP

Rys. 1. Architektura ćwiczeń z programowania

Czego się dowiesz

Jak wdrożyć bramę agentów w uporządkowanej sekwencji konfiguracji
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
Sprawdzanie dzienników Bramy agentów w celu weryfikacji zarządzania ruchem wychodzącym

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

Podczas wdrażania bramy agenta z kontrolami zarządzania ważne jest, aby postępować zgodnie z ustrukturyzowaną sekwencją konfiguracji. Dzięki temu agenci będą mieli dostęp do niezbędnych zasobów podczas inicjowania, a żądania sieciowe będą realizowane z powodzeniem.

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

Uruchom w trybie próbnym: jeśli środowisko wykonawcze agenta jest skonfigurowane do kierowania połączeń wychodzących do bramy przed jej pełnym udostępnieniem, zadanie nie zostanie zainicjowane. Skonfigurowanie rozszerzenia autoryzacji bramy w trybie DRY_RUN zapewnia, że gdy ruch agenta dotrze do bramy, żadne żądania nie zostaną odrzucone.
Zarejestruj wszystkie usługi: wszyscy agenci, serwery MCP i punkty końcowe, które korzystają z bramy agenta, muszą być zarejestrowane w rejestrze agentów. Żądania z niezarejestrowanych źródeł lub miejsc docelowych są odrzucane. Agenty wdrożone w środowisku wykonawczym Agent Runtime i na serwerach Google MCP są rejestrowane automatycznie. Każdy punkt końcowy interfejsu API Google lub niestandardowy serwer MCP musi zostać zarejestrowany ręcznie.
Wymuszanie zasad autoryzacji: zasady autoryzacji służą do przyznawania zarejestrowanym agentom dostępu do komponentów agenta przez przyznanie roli roles/iap.egressor tożsamości agenta i powiązanie jej z docelowym zasobem rejestru. Oceń zachowanie agenta w trybie próbnym, a następnie zdefiniuj zasady, które pozwolą na przepuszczanie wybranego ruchu wychodzącego przez bramę. Po wprowadzeniu zasad przełącz się na tryb ENFORCED, aby umożliwić bramie aktywne egzekwowanie zasad zarządzania.

Rys. 2. Sekwencja wdrażania

Topologia routingu ruchu wychodzącego

Bramy zwykle zarządzają ruchem przychodzącym (ingress) do usług backendu. Brama agenta działająca w trybie ruchu wychodzącego (od agenta do dowolnego miejsca) pełni funkcję scentralizowanego, opartego na zasadzie zerowego zaufania serwera proxy ruchu wychodzącego dla zadań agenta.

Gdy aplikacja AI lub zadanie agenta próbuje wywołać zewnętrzne narzędzie lub interfejs API, żądanie wychodzące jest przechwytywane przez Agent Gateway i oceniane pod kątem zasad zarządzania przed przekierowaniem do miejsca docelowego:

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 Cloud API Google, modeli podstawowych, punktów końcowych Google MCP (np. BigQuery) i usług zarządzania platformą (Agent Registry i zasady IAP).

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 Agent Runtime, który jest kierowany do zdalnego punktu końcowego serwera MCP Google dla BigQuery.

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 agentów
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ń Agent Runtime
Zasady ruchu wychodzącego	`roles/iap.admin`	Stosowanie zasad `roles/iap.egressor`
BigQuery	`roles/bigquery.admin`	Konfigurowanie schematów i testowanie zbiorów danych
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

Możesz też użyć szerokiego poziomu podstawowego, 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 w chmurze Google Cloud:

Cloud Shell na stronie shell.cloud.google.com lub
Terminal lokalny z zainstalowanym interfejsem wiersza poleceń gcloud

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)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}

# 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-dj"
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}"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}

# create local dir for config files
mkdir -p cfg

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 \
  discoveryengine.googleapis.com

To kończy część konfiguracji... przejdźmy teraz do sekcji Brama.

4. Brama

Przed wprowadzeniem kontroli dostępu wdróż bramę agentów i skonfiguruj jej rozszerzenie autoryzacji w 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 regionalnego rejestru do obsługi regionalnych zasobów Agent Runtime.

Utwórz bramę

# create agent gateway config file (regional registry)
cat > cfg/${AGW_NAME}.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
EOF

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

# show agent gateway details (verify deployment state)
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

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

5. Autoryzacja

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

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 dotyczących 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.
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.
Warstwa powiązań: rozszerzenie usługi jest połączone z bramą agentów za pomocą zasady autoryzacji skonfigurowanej z profilem REQUEST_AUTHZ.

Rozszerzenie autoryzacji

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

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

# show authz extension details (verify extension state)
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

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

# show authz policy details (verify dry run mode)
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.

6. Baza kodu

Kod agenta, zbiór danych BigQuery i skrypt rejestracji używane w tym ćwiczeniu są przechowywane w zdalnym repozytorium GitHub Google Cloud. Poniższe kroki spowodują sklonowanie repozytorium lokalnie, skopiowanie niezbędnych plików do bieżącej struktury katalogów roboczych, a następnie czyszczenie niepotrzebnych plików tymczasowych.

Tworzony jest zasobnik tymczasowy na dane, do którego Agent Runtime 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_gmcp

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/agent-dj ./agent-dj
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/endpoints ./endpoints

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_gmcp

Tworzenie zbioru danych BigQuery

# create bq dataset schema and load data
bq --project_id=${PROJ_ID} query \
  --use_legacy_sql=false < agent-dj/setup.sql

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.

7. 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. Tryb wychodzący bramy agentów (agent-to-anywhere) używa modelu danych rejestru jako struktury 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ć agentów korzystających z różnych interfejsów API Google i usług Google, używany jest skrypt, który szybko rejestruje wspólny zestaw punktów końcowych interfejsu API przy użyciu nazw hostów i lokalizacji z endpoints/googleapis.txt.

Rejestrowanie punktów końcowych

# run python script to register google api endpoints
python3 endpoints/register_endpoints.py \
  --multi-region=${MREGION} \
  --region=${REGION} \
  --mtls-endpoints=include

Weryfikowanie punktów końcowych

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

To koniec części dotyczącej rejestru. Przejdźmy teraz do sekcji Środowisko wykonawcze.

8. Środowisko wykonawcze

agent-dj Agent ADK wdrożony w środowisku Agent Runtime jest skonfigurowany w skrypcie wdrożenia z tymi ustawieniami, aby zintegrować go z usługą Agent Platform:

"identity_type": types.IdentityType.AGENT_IDENTITY – udostępnia unikalną tożsamość podmiotu zabezpieczeń opartą na SPIFFE dla agenta.
"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.

Wdrażanie agenta

# deploy agent runtime workload
uv --directory agent-dj 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 dj contact info" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --allow-token-sharing

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 AGENT_UID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${AGENT_UID}

Weryfikowanie wpisu w rejestrze

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

agentId: urn:agent:projects-${PROJ_NO}:projects:${PROJ_NO}:locations:${REGION}:aiplatform:reasoningEngines:${RE_ENGINE_ID}
attributes:
  agentregistry.googleapis.com/system/Framework:
    framework: google-adk
  agentregistry.googleapis.com/system/RuntimeIdentity:
    principal: principal://agents.global.org-${PROJ_NO}.system.id.goog/resources/aiplatform/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
  agentregistry.googleapis.com/system/RuntimeReference:
    uri: //aiplatform.googleapis.com/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
createTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'
description: agent for dj contact info
displayName: agent-dj
name: projects/${PROJ_ID}/locations/${REGION}/agents/agentregistry-${RE_AGENT_ID}
protocols:
- interfaces:
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:query
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:streamQuery
  type: CUSTOM
uid: agentregistry-00000000-0000-0000-1234-4567abcd1234
updateTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'

Weryfikowanie konfiguracji bramy

# verify agent gateway routing specification
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 agentowi ról uprawnień do zasobów

Uprawnienia do ról IAM w przypadku zasobów umożliwiają tożsamości głównej agenta dostęp do BigQuery, narzędzi MCP (w przypadku interfejsów API Google) i innych wymaganych usług platformy AI. Te zasady są egzekwowane za pomocą usługi IAM na poziomie zasobu.

# grant bigquery query execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.user"

# grant bigquery data viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.dataViewer"

# grant mcp tool execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/mcp.toolUser"

# 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 ról uprawnień agenta w przypadku zasobów

# verify active role bindings for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="value(bindings.role)"

To wszystko, jeśli chodzi o czas działania. Przejdźmy teraz do sekcji Zasady.

9. Zasady

Zasady autoryzacji zarządzania agentami zezwalają na ruch z agenta AI przez bramę agentów do miejsca docelowego (np. punktu końcowego serwera MCP Google Cloud w przypadku BigQuery). Gdy ruch dotrze do miejsca docelowego, dostęp do danych będzie autoryzowany przez zwykłe uprawnienia IAM (które zostały włączone w poprzedniej sekcji).

Przyznawanie ról IAM na potrzeby ruchu wychodzącego z bramy agentów umożliwia stosowanie zasad dostępu, które pozwalają 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 agentowi 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ń Agent Runtime w wybranym zasobie docelowym zezwala na ten ruch wychodzący. W tym ćwiczeniu rola jest przypisywana do zbioru podmiotów zabezpieczeń, co przyznaje uprawnienia wszystkim tożsamościom agentów środowiska wykonawczego agenta w projekcie.

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 agents, mcpServers i endpoints. W tym samouczku zasady IAM są powiązane z poziomem rejestru, co powoduje zastosowanie uprawnień do wszystkich zasobów podrzędnych.

Konfigurowanie uprawnień rejestru regionalnego IAP

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

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

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

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

# verify iap iam policy for regional registry
gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION}

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

10. Kontrola

Rozszerzenie autoryzacji bramy agentów działa w trybie DRY_RUN. Żądania wychodzące są obserwowane i rejestrowane, ale nie blokowane.

Testowanie zapytań do agenta

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

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

Możesz też wpisać to polecenie w terminalu i kliknąć link, aby przejść do platformy testowej 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…

How many DJs do we have on file?
What is the phone number of DJ Cosmopup?

Sprawdź, czy zapytania zwracają prawidłowe odpowiedzi (np. „W bazie jest 12 DJ-ów”).

Analizowanie logów kontrolnych

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

# query gateway logs for dry run
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
  )"

TIMESTAMP            METHOD  STATUS  IAP_AUTHZ  MCP_METHOD  URL
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://telemetry.googleapis.com/v1/traces
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp

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

11. Egzekwuj

Agentowi udało się wysłać żądania przez bramę w trybie DRY_RUN. Przejdź na tryb ENFORCE rozszerzenia autoryzacji IAP bramy agenta, aktualizując zasadę autoryzacji.

Aktualizowanie 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

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

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

Aktualizowanie 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

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

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

Prześlij dodatkowe zapytanie testowe…

What DJ Fishfry's credit card number?

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

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

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

12. Czyszczenie

# delete agent
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

# remove agent resource iam bindings
for ROLE in \
  "roles/bigquery.user" \
  "roles/bigquery.dataViewer" \
  "roles/mcp.toolUser" \
  "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 storage bucket
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}

# delete bigquery dataset and contents
bq rm -r -f -d ${PROJ_ID}:dj_ds

# next

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

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

# next

# delete gateway resources
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}

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

# next

# clean up local working directories and generated configs
rm -rf cfg agent-dj endpoints

# end

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

13. Podsumowanie

Gratulacje! Udało Ci się wdrożyć i zarządzać komunikacją wychodzącą agenta, który uzyskuje dostęp do narzędzi za pomocą bramy agenta.

cosmopup

Cosmopup uważa, że ćwiczenia z programowania są najlepsze!

Co dalej?

Zaawansowane funkcje i samouczki znajdziesz w dokumentacji Gemini Enterprise Agent Platform.
Skonfiguruj bariery Model Armor w bramie agentów, aby zwiększyć bezpieczeństwo AI.
Poznaj zasady zarządzania semantycznego, aby egzekwować reguły biznesowe i zgodność w przypadku zapytań w języku naturalnym.

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

Dziękujemy!