Zarządzanie obciążeniami agentowymi za pomocą bramy agenta na platformie agentów Gemini Enterprise

1. Wprowadzenie

Platforma agentów Gemini Enterprise to otwarta platforma do tworzenia, skalowania i optymalizowania agentów AI klasy korporacyjnej oraz do zarządzania nimi. Agenci ci są oparci na Twoich danych.

Środowisko wykonawcze agenta zapewnia zarządzane środowisko wykonawcze do bezpiecznego uruchamiania w Google Cloud agentów, takich jak te utworzone za pomocą pakietu Agent Development Kit (ADK) o otwartym kodzie źródłowym.

Z tego ćwiczenia dowiesz się, jak używać tych podstawowych elementów składowych do zarządzania agentem zainicjowanym przez użytkownika w Gemini Enterprise, który bezpiecznie korzysta z narzędzi wewnętrznych.

Informacje o bramie agenta

Brama agentów to komponent sieciowy pakietu zarządzania agentami na platformie. Działa ona jako punkt wejścia i wyjścia sieci dla wszystkich interakcji z agentem, co umożliwia administratorom zabezpieczeń egzekwowanie scentralizowanego zarządzania bez konieczności zarządzania przez deweloperów złożonymi elementami sieci.

Umożliwia 2 główne zarządzane ścieżki dostępu:

  • Klient – agent (wejście): zabezpiecza komunikację między klientami zewnętrznymi (np. Cursor lub interfejs wiersza poleceń Gemini) a Twoimi agentami.
  • Agent-to-Anywhere (ruch wychodzący): zabezpiecza komunikację między agentami działającymi w Google Cloud a serwerami, narzędziami lub interfejsami API działającymi w dowolnym miejscu.

W tym ćwiczeniu skupisz się na trybie Od agenta do dowolnego miejsca (ruch wychodzący).

Kontrola dostępu za pomocą bramy agenta

Aby egzekwować zasady zabezpieczeń, brama agentów jest ściśle zintegrowana z pozostałą częścią ekosystemu:

  • Rejestr agentów: centralna biblioteka zatwierdzonych agentów i narzędzi (w tym serwerów MCP innych firm).
  • Tożsamość agenta: unikalna, możliwa do śledzenia tożsamość każdego agenta, automatycznie zabezpieczana za pomocą kompleksowego protokołu mTLS.
  • Identity-Aware Proxy (IAP) i IAM: domyślna warstwa egzekwowania, która weryfikuje tożsamość agenta na podstawie szczegółowych uprawnień IAM przed zezwoleniem na wywołania konkretnych narzędzi.
  • Model Armor: zabezpieczenie AI zintegrowane za pomocą Service Extensions, które oczyszcza treści i chroni przed atakami polegającymi na wstrzykiwaniu promptów oraz wyciekami danych.

Tryby wdrażania (sieć publiczna a prywatna w Cloud Run)

Aby to ćwiczenie było dostępne, możesz wybrać jedną z 2 ścieżek sieciowych dla narzędzi wewnętrznych (serwerów MCP) wdrożonych w Cloud Run:

  1. Domyślne (publiczne wejście): serwery MCP są wdrażane w Cloud Run z publicznymi nazwami hostów (ingress=all). Ruch jest kierowany z agenta do narzędzi za pomocą standardowych adresów URL *.run.app. Nie wymaga to niestandardowych domen DNS i jest najszybszym sposobem na poznanie koncepcji zarządzania.
  2. Bezpieczna (sieć prywatna): opcjonalna, w pełni prywatna architektura. Serwery MCP są ograniczone (ingress=internal-and-cloud-load-balancing) i udostępniane za pomocą wewnętrznego systemu równoważenia obciążenia aplikacji z bezserwerową grupą punktów końcowych sieci. Aby udostępnić certyfikat zarządzany przez Google, musisz mieć publiczną domenę DNS.

Preferowaną ścieżkę wybierzesz podczas konfigurowania Terraform.

Więcej informacji o ruchu przychodzącym do punktów końcowych sieci w Cloud Run znajdziesz w naszej dokumentacji.

Jakie zadania wykonasz

  • Zainicjuj podstawowy stos infrastruktury za pomocą Terraform
  • Kompilowanie i wdrażanie narzędzi wewnętrznych jako serwerów MCP w Cloud Run
  • Wdrażanie agenta ADK w środowisku wykonawczym agentów za pomocą wychodzącego interfejsu PSC
  • Konfigurowanie rozszerzeń usług bramy agenta na potrzeby dostępu opartego na tożsamości (IAM) i filtrowania treści (Model Armor)
  • Śledzenie i weryfikowanie bezpiecznego kompleksowego działania agenta

Czego potrzebujesz

  • przeglądarka, np. Chrome;
  • Projekt Google Cloud z włączonymi płatnościami i dostępem Właściciel
  • Uprawnienia IAM na poziomie organizacji (w tym samouczku przyznawane są role o zakresie organizacji)
  • domena, nad którą masz kontrolę i która jest delegowana do Cloud DNS (w przypadku publicznego certyfikatu zarządzanego);
  • Znajomość Terraform, gcloud i podstawowych funkcji sieciowych Google Cloud.

Topologia ćwiczeń z programowania

Architektura kompleksowa: Gemini Enterprise – środowisko wykonawcze agenta – brama agenta – serwery MCP w Cloud Run

W tym ćwiczeniu wdrożysz kompleksowego agenta do oceny ryzyka kredytowego, który bezpiecznie komunikuje się z 3 narzędziami wewnętrznymi.

Zaczniesz od udostępnienia podstawowej sieci, w tym sieci VPC i wewnętrznego systemu równoważenia obciążenia aplikacji skonfigurowanego jako brama agenta. Następnie wdrożysz w Cloud Run 3 serwery Model Context Protocol (MCP). Są to Twoje wewnętrzne narzędzia zastrzeżone:

  • Zarządzanie dokumentami (legacy-dms)
  • E-mail służbowy (corporate-email)
  • Weryfikacja dochodu (income-verification)

Po skonfigurowaniu narzędzi wdrożysz w środowisku wykonawczym agentów asystenta ds. kredytów hipotecznych (mortgage-agent) utworzonego za pomocą pakietu ADK. Skonfigurujesz tego agenta tak, aby używał interfejsu PSC do prywatnego ruchu wychodzącego i umożliwiał wykrywanie narzędzi w czasie działania za pomocą rejestru agentów.

Aby zabezpieczyć przepływ, skonfigurujesz bramę agenta za pomocą 2 rozszerzeń usługi. Najpierw REQUEST_AUTHZrozszerzenie zweryfikuje tożsamość agenta na podstawie zasad uprawnień dotyczących poszczególnych narzędzi, aby mieć pewność, że agent ma dostęp tylko do autoryzowanych narzędzi. Po drugie, CONTENT_AUTHZ rozszerzenie korzystające z Model Armor będzie filtrować prompty i odpowiedzi agenta.

Na koniec zarejestrujesz agenta w Gemini Enterprise, uruchomisz zadanie oceny ryzyka kredytowego jako użytkownik i sprawdzisz bezpieczne, kontrolowane wykonanie za pomocą Cloud Trace.

To laboratorium jest przeznaczone dla inżynierów platform i inżynierów ds. bezpieczeństwa na wszystkich poziomach zaawansowania. Wypełnienie go zajmie Ci około 100 minut.

2. Zanim zaczniesz

Tworzenie projektu i uwierzytelnianie

Utwórz nowy projekt GCP (lub użyj istniejącego) z włączonym rozliczeniem, a następnie uwierzytelnij Cloud Shell lub komputer lokalny:

gcloud auth login
gcloud auth application-default login
gcloud config set project <your-project-id>

Włączanie interfejsów API do uruchamiania

Moduł podstawowy Terraform włącza około 30 interfejsów API przy pierwszym zastosowaniu, ale w przypadku terraform init i zasobnika stanu GCS wymagany jest mały zestaw początkowy:

gcloud services enable \
  compute.googleapis.com \
  serviceusage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  iam.googleapis.com \
  storage.googleapis.com \
  dns.googleapis.com

Instalowanie wymaganych narzędzi

Zainstaluj zestaw narzędzi. W Cloud Shell większość z nich jest już dostępna, a na stacji roboczej:

# uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# skaffold
curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64 && \
  sudo install skaffold /usr/local/bin/

# envsubst (gettext)
sudo apt-get install -y gettext-base

Potrzebujesz też Terraform w wersji >= 1.12.2, Pythona w wersji 3.12 lub nowszej oraz pakietu SDK Google Cloud (gcloud).

Ustawianie zmiennych środowiskowych

W dalszej części tego laboratorium zakłada się, że są one wyeksportowane w powłoce.

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export ORG_ID=$(gcloud projects get-ancestors $PROJECT_ID | awk '$2 == "organization" {print $1}')
export REGION="us-central1"

# Only required if using the secure private networking path
export DOMAIN_NAME="agw.example.com"

Sprawdź, czy wszystkie zmienne zostały poprawnie wypełnione. Powinny zostać zwrócone 3 wartości.

echo $PROJECT_ID  
echo $PROJECT_NUMBER
echo $ORG_ID

Jeśli identyfikator organizacji nie zostanie wypełniony automatycznie, możesz go znaleźć i ustawić ręcznie.

gcloud organizations list
export ORG_ID=ID_FROM_OUTPUT

3. Klonowanie repozytorium 

git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git
cd cloud-networking-solutions
cd demos/agent-gateway

Krótki przegląd zawartości katalogu wersji demonstracyjnych:

src/                MCP servers (legacy-dms, corporate-email, income-verification-api) + mortgage-agent
terraform/          Root Terraform config + modules (foundation, networking, agent-gateway, model-armor, ...)
cloudrun/           Cloud Run service definitions (rendered from .yaml.tmpl via envsubst)
scripts/            grant_agent_mcp_egress.sh — per-MCP IAP egressor binding
skaffold.yaml.tmpl  Skaffold pipeline that builds + deploys all three MCP services to Cloud Run

4. Tworzenie zasobnika stanu Terraform i konfiguracji backendu

Utwórz zasobnik GCS do przechowywania stanu zdalnego, a następnie skopiuj szablon backendu:

gcloud storage buckets create gs://${PROJECT_ID}-tfstate \
  --location=${REGION} \
  --uniform-bucket-level-access

cp terraform/example.backend.conf terraform/backend.conf

Zastąp terraform/backend.conf swoimi wartościami:

bucket = "<your-project-id>-tfstate"
prefix = "agent-gateway"

5. (Opcjonalnie) Tworzenie publicznej strefy DNS w Cloud DNS

W tym laboratorium usługa Cloud Run ma domyślnie ustawioną konfigurację wejścia na all, a rejestr agentów rejestruje każdy serwer MCP pod jego publicznym adresem URL *.run.app – nie są wymagane żadne dodatkowe ustawienia DNS, certyfikaty ani moduł równoważenia obciążenia. Jeśli chcesz przełączyć się na sieć prywatną (Cloud Run z ingress = internal-and-cloud-load-balancing za wewnętrznym modułem równoważenia obciążenia aplikacji), potrzebujesz też publicznej strefy DNS Cloud DNS, aby usługa menedżer certyfikatów mogła zweryfikować certyfikat modułu równoważenia obciążenia.

Przepływ zadań wysokiego poziomu w przypadku sieci prywatnych

Przepływ zadań wysokiego poziomu w przypadku opcji sieci prywatnej

Aby użyć podejścia opartego na sieci prywatnej:

  1. Utwórz publiczną strefę Cloud DNS – menedżer certyfikatów zweryfikuje regionalny certyfikat zarządzany, zapisując w niej rekordy CNAME:
gcloud dns managed-zones create agw-example-com \
  --dns-name="${DOMAIN_NAME}." \
  --description="Public zone for ${DOMAIN_NAME}" \
  --visibility=public

Odpowiednia strefa prywatna dla mcp.${DOMAIN_NAME} (używana przez wewnętrzny moduł równoważenia obciążenia MCP i peering DNS z Agent Runtime) jest tworzona automatycznie przez Terraform – nie musisz jej tworzyć ręcznie. Gdy sieć prywatna jest wyłączona, nie jest udostępniana ani strefa publiczna, ani prywatna.

6. Konfigurowanie zmiennych Terraform

Skopiuj przykładowy plik tfvars i go zmodyfikuj:

cp terraform/example.tfvars terraform/terraform.tfvars

Dostępne są 2 ścieżki demonstracyjne, do których dostęp jest ograniczony przez parametr enable_cloud_run_private_networking.

Ścieżka domyślna: Cloud Run z publicznym ruchem przychodzącym

**Najprostsza konfiguracja.**W przypadku ścieżki domyślnej wystarczy edytować 3 wartości w terraform.tfvars. Wszystkie pozostałe zmienne w pliku mają już domyślne wartości odpowiednie dla wersji demonstracyjnej.

# GCP project ID where all resources will be created.
project_id = "my-gcp-project-id"

# GCP organization ID (numeric).
organization_id = "123456789012"

# Members granted demo-wide roles
platform_admin_members = ["user:admin@example.com"]

# IAP Enforcement Mode ("DRY_RUN" or null)
agent_gateway_iap_iam_enforcement_mode = "DRY_RUN"

Sieć prywatna (opcjonalnie)

Ustaw enable_cloud_run_private_networking = true i dodaj poniższe zmienne, aby udostępnić pełny bezpieczny stos:

  • Wewnętrzny system równoważenia obciążenia aplikacji
  • Certyfikat zarządzany przez Google
  • Cloud Run z ingress = internal-and-cloud-load-balancing
  • Połączenie równorzędne DNS usługi bramy agentów.
enable_cloud_run_private_networking = true

# DNS — must end with a trailing dot, must match a Cloud DNS zone you own
dns_zone_domain            = "agw.example.com."
enable_certificate_manager = true

# mcp_internal_dns_zone.domain MUST be a real subdomain of dns_zone_domain so
# Certificate Manager can issue a Google-managed cert.
mcp_internal_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

# Must match mcp_internal_dns_zone.domain so Agent Engine resolves MCP
# hostnames over the PSC interface peering.
psc_interface_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

mcp_lb_protocol = "HTTPS"

7. Wdrażanie infrastruktury za pomocą Terraform

Inicjowanie, sprawdzanie i stosowanie:

cd terraform
terraform init -backend-config=backend.conf
terraform plan
terraform apply

terraform apply udostępnia około 40 zasobów na ścieżce domyślnej i zajmuje 8–10 minut w przypadku nowego projektu (około 60 zasobów / 15–20 minut w przypadku enable_cloud_run_private_networking = true). Tworzy:

  • Podstawa projektu (interfejsy API, tożsamości usług, limity)
  • VPC, podsieci (podstawowe, tylko proxy, PSC, PSC-Interface, kolokacja bramy agenta), Cloud NAT, reguły zapory sieciowej
  • Repozytorium Artifact Registry na potrzeby obrazów Cloud Run
  • 3 usługi Cloud Run + SA środowiska wykonawczego dla każdej usługi (ruch przychodzący = all domyślnie; internal-and-cloud-load-balancing, gdy włączona jest sieć prywatna)
  • Szablon Model Armor + IAM
  • Brama agenta, załącznik sieci PSC-I, rozszerzenia IAP i Model Armor, obie zasady autoryzacji i uprawnienie roles/iap.egressor na poziomie projektu
  • Punkty końcowe rejestru agentów (Vertex AI, IAP, Discovery Engine itp.) oraz 3 serwery MCP (zarejestrowane domyślnie w *.run.app/mcp, a w ./mcp, gdy włączona jest sieć prywatna).

Tylko wtedy, gdy enable_cloud_run_private_networking = true:

  • Wewnętrzny regionalny moduł równoważenia obciążenia aplikacji z bezserwerową grupą punktów końcowych sieci (routing z maskowaniem adresu URL) + prywatne rekordy A DNS
  • Prywatna strefa DNS MCP (mcp..) dołączona do sieci VPC
  • Moduł publicznej strefy DNS (autoryzacje DNS w menedżerze certyfikatów) + regionalny certyfikat zarządzany przez Google
  • Strefa DNS interfejsu PSC (osierocona, gdy nie ma prywatnych nazw hostów do rozpoznania, więc jest też zależna od głównej flagi)
  • Połączenie równorzędne DNS bramy agenta w domenie mcp.. (dodane automatycznie)

8. Sprawdzanie punktów końcowych rejestru agentów

Rejestr agentów to katalog usług (interfejsów API Google i własnych serwerów MCP) w projekcie, które agent wykrywa w czasie działania. Agent hipoteczny odczytuje go podczas uruchamiania i dynamicznie wiąże narzędzia – w kodzie agenta ani w poleceniu wdrożenia nie ma adresów URL MCP.

Punkty końcowe

Co Terraform uruchomił w Twoim imieniu – w przypadku każdego interfejsu API Google w agent_registry_google_apis zarejestrował 5 wariantów (globalny, globalny mTLS, regionalny, regionalny mTLS, regionalny REP). Na przykład w przypadku aiplatform:

gcloud alpha agent-registry services create aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-mtls \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform mTLS" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.mtls.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create ${REGION}-aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Locational" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://${REGION}-aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-${REGION}-rep \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Regional (REP)" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.${REGION}.rep.googleapis.com,protocolBinding=JSONRPC"

Serwery MCP

Terraform rejestruje też 3 serwery MCP. Aby zarejestrować inne serwery MCP, możesz wykonać czynności opisane w dokumentacji.

gcloud alpha agent-registry services create legacy-dms \
--project=${PROJECT_ID} \
--location=${REGION} \
--display-name="Legacy DMS" \
--mcp-server-spec-type=tool-spec \
--mcp-server-spec-content=src/legacy-dms/toolspec.json \
--interfaces=url=https://dms.${DOMAIN_NAME}/mcp,protocolBinding=JSONRPC

Sprawdź zarejestrowane punkty końcowe i serwery MCP.

gcloud alpha agent-registry services list \
  --project=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

gcloud alpha agent-registry mcp-servers list \
  --project=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

Źródło: terraform/modules/agent-registry-endpoints/scripts/register_endpoints.sh.tpl.

9. Sprawdzanie konfiguracji bramy agenta

Brama agenta to zarządzana przez Google płaszczyzna zarządzania między środowiskiem wykonawczym agenta a Twoimi narzędziami. W trybie AGENT_TO_ANYWHERE jest powiązany z rejestrem agentów projektu i wychodzi przez interfejs PSC należący do klienta, dzięki czemu może docierać do prywatnych serwerów MCP w sieci VPC.

Jeśli importujesz tę bramę ręcznie, plik YAML będzie wyglądać tak:

# agent-gateway.yaml — for reference only, Terraform already created this
name: agent-gateway
protocols: [MCP]
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJECT_ID}/locations/${REGION}"
networkConfig:
  egress:
    networkAttachment: projects/${PROJECT_ID}/regions/${REGION}/networkAttachments/agent-gateway-na
  dnsPeeringConfig:
    domains:
      - mcp.${DOMAIN_NAME}.
    targetProject: ${PROJECT_ID}
    targetNetwork: projects/${PROJECT_ID}/global/networks/gateway-vpc

gcloud alpha network-services agent-gateways import agent-gateway \
  --source=agent-gateway.yaml \
  --location=${REGION}

Sprawdź, czy Terraform utworzył bramę:

gcloud alpha network-services agent-gateways describe agent-gateway \
  --location=${REGION}

10. Sprawdzanie autoryzacji IAP i Model Armor

Brama agentów deleguje autoryzację na rozszerzenia usług. W wersji demonstracyjnej obowiązują 2 profile zasad:

  • REQUEST_AUTHZ – oceniane raz na żądanie na etapie nagłówków. Używane tutaj do wywoływania IAP, które sprawdza, czy tożsamość wywołującego agenta ma roles/iap.egressor na docelowym serwerze MCP.
  • CONTENT_AUTHZ – przesyła do rozszerzenia zdarzenia dotyczące treści w celu ich oczyszczenia. Używane tutaj do wywoływania Model Armor, która sprawdza, czy nie występują wstrzykiwanie promptów, jailbreaki, naruszenia zasad dotyczących odpowiedzialnej AI i (opcjonalnie) informacje umożliwiające identyfikację za pomocą usługi Sensitive Data Protection (SDP).

Rozszerzenie IAP REQUEST_AUTHZ

cat > iap-authz-extension.yaml <<EOF
name: agent-gateway-iap-authz
service: iap.googleapis.com
failOpen: true
timeout: 1s
EOF

gcloud beta service-extensions authz-extensions import agent-gateway-iap-authz \
  --source=iap-authz-extension.yaml \
  --location=${REGION} \
  --project=${PROJECT_ID}

Powiąż ją z bramą agenta za pomocą zasady REQUEST_AUTHZ:

curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-iap-policy" \
  -d '{
    "name": "agent-gateway-iap-policy",
    "policyProfile": "REQUEST_AUTHZ",
    "action": "CUSTOM",
    "target": {
      "resources": [
        "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
      ]
    },
    "customProvider": {
      "authzExtension": {
        "resources": [
          "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-iap-authz"
        ]
      }
    }
  }'

Rozszerzenie Model Armor CONTENT_AUTHZ

Rozszerzenie metadata.model_armor_settings zawiera identyfikatory szablonów żądań i odpowiedzi, których Model Armor używa do oceny każdego wywołania:

cat > ma-extension.yaml <<EOF
name: agent-gateway-ma-authz
service: modelarmor.${REGION}.rep.googleapis.com
failOpen: true
timeout: 1s
metadata:
  model_armor_settings: '[
    {
      "request_template_id":  "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-request-template",
      "response_template_id": "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-response-template"
    }
  ]'
EOF

gcloud beta service-extensions authz-extensions import agent-gateway-ma-authz \
  --source=ma-extension.yaml \
  --location=${REGION} \
  --project=${PROJECT_ID}

curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-ma-policy" \
  -d '{
    "name": "agent-gateway-ma-policy",
    "policyProfile": "CONTENT_AUTHZ",
    "action": "CUSTOM",
    "target": {
      "resources": [
        "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
      ]
    },
    "customProvider": {
      "authzExtension": {
        "resources": [
          "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-ma-authz"
        ]
      }
    }
  }'

Szablony DLP niestandardowe

Model Armor sdpSettings.basicConfig korzysta z wbudowanej listy typów informacji. Aby uzyskać większą kontrolę (niestandardowe typy informacji, częściowe maskowanie, zastępowanie danymi zastępczymi, redagowanie według prawdopodobieństwa), skieruj Model Armor na własne szablony Cloud DLP inspect i de-identify za pomocą sdpSettings.advancedConfig.

Utwórz szablon inspekcji, który będzie oznaczać numery ubezpieczenia społecznego w Stanach Zjednoczonych z prawdopodobieństwem POSSIBLE lub wyższym:

curl -fsS -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://dlp.googleapis.com/v2/projects/${PROJECT_ID}/locations/${REGION}/inspectTemplates" \
  -d '{
    "templateId": "agw-ssn-inspect-template",
    "inspectTemplate": {
      "displayName": "SSN Inspect Template",
      "inspectConfig": {
        "infoTypes": [
          { "name": "US_SOCIAL_SECURITY_NUMBER" }
        ],
        "minLikelihood": "POSSIBLE"
      }
    }
  }'

Utwórz szablon deidentyfikacji, który zastępuje każdy wynik tokenem typu informacji (np. [US_SOCIAL_SECURITY_NUMBER]):

curl -fsS -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://dlp.googleapis.com/v2/projects/${PROJECT_ID}/locations/${REGION}/deidentifyTemplates" \
  -d '{
    "templateId": "agw-ssn-redaction-template",
    "deidentifyTemplate": {
      "displayName": "SSN Redaction Template",
      "deidentifyConfig": {
        "infoTypeTransformations": {
          "transformations": [{
            "primitiveTransformation": { "replaceWithInfoTypeConfig": {} }
          }]
        }
      }
    }
  }'

Następnie wskaż parę w konfiguracji odpowiedzi szablonu Model Armor za pomocą sdpSettings.advancedConfig (w tym miejscu moduł model_armor Terraformu ustawiłby advanced_config, gdyby został skonfigurowany):

{
  "filterConfig": {
    "sdpSettings": {
      "advancedConfig": {
        "inspectTemplate":    "projects/${PROJECT_ID}/locations/${REGION}/inspectTemplates/agw-ssn-inspect-template",
        "deidentifyTemplate": "projects/${PROJECT_ID}/locations/${REGION}/deidentifyTemplates/agw-ssn-redaction-template"
      }
    }
  }
}

Uprawnienia IAM dotyczące ruchu wychodzącego z IAP (tylko na serwerze MCP)

Terraform nie tworzy powiązania roles/iap.egressor w całym projekcie w niejawnym rejestrze agentów IAP. Wiązanie IAP REQUEST_AUTHZ jest w rzeczywistości oceniane na serwer MCP i na silnik wnioskowania. Jest ono przyznawane po wdrożeniu agenta i poznaniu jego identyfikatora. W tym celu w kroku „Grant the agent per-MCP-server egress” (Przyznaj agentowi uprawnienia do wychodzącego ruchu sieciowego na poszczególnych serwerach MCP) uruchamiana jest usługa scripts/grant_agent_mcp_egress.sh.

11. Kompilowanie i wdrażanie serwerów MCP w Cloud Run

Pliki cloudrun/*.yaml.tmpl i skaffold.yaml.tmpl odwołują się do plików ${PROJECT_ID}, ${REGION} i ${MCP_INGRESS} (adnotacja wejścia Cloud Run). Źródło MCP_INGRESS z danych wyjściowych Terraform, aby renderowane manifesty były zsynchronizowane z enable_cloud_run_private_networking, a następnie renderuj za pomocą envsubst:

Wyeksportuj konfigurację ruchu przychodzącego Cloud Run.

  • all
  • internal-and-cloud-load-balancing (w przypadku korzystania z podejścia opartego na sieci prywatnej)
export MCP_INGRESS=all

envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < skaffold.yaml.tmpl > skaffold.yaml
for f in cloudrun/*.yaml.tmpl; do
  envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < "$f" > "${f%.tmpl}"
done

Każda usługa Cloud Run działa jako utworzone przez Terraform wykonawcze konto usługi (np. mcp-legacy-dms@${PROJECT_ID}.iam.gserviceaccount.com). Aby wdrożyć usługę jako te konta usługi, musisz mieć uprawnienie roles/iam.serviceAccountUser:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="user:$(gcloud config get-value account)" \
  --role="roles/iam.serviceAccountUser"

Kompilowanie za pomocą Cloud Build i wdrażanie za pomocą Skaffold:

skaffold run

Skaffold tworzy 3 obrazy (legacy-dms, corporate-email, income-verification-api) w repozytorium Artifact Registry i aktualizuje każdą usługę Cloud Run, aby wskazywała nowy skrót.

Zweryfikuj:

gcloud run services list --region=${REGION}

Powinny być widoczne wszystkie 3 usługi ze stanem ACTIVE.

12. Wdróż agenta hipotecznego w środowisku wykonawczym agentów

Zainstaluj zależności agenta i wdroż go:

cd src/mortgage-agent
uv sync

uv run python deploy_agent.py \
  --project=${PROJECT_ID} \
  --region=${REGION} \
  --enable-agent-identity \
  --agent-name=mortgage-agent \
  --agent-gateway=projects/${PROJECT_ID}/locations/${REGION}/agentGateways/agent-gateway \
  --model-endpoint-location=global

Po zakończeniu działania skryptu skopiuj wydrukowany znak reasoningEngines/ do powłoki:

export AGENT_ID=<numeric-id-from-output>
cd ../..

13. Przyznaj agentowi dostęp wychodzący do poszczególnych serwerów MCP

Rozszerzenie IAP REQUEST_AUTHZ autoryzuje każde wywołanie narzędzia, sprawdzając roles/iap.egressor agenta na konkretnym serwerze MCP lub punkcie końcowym, do którego wywołuje. Zobacz Tworzenie zasad ruchu wychodzącego dla połączeń agenta z serwerem MCP.

Skrypt (scripts/grant_agent_mcp_egress.sh) wylicza serwery MCP w rejestrze agentów w sekcji projects/${PROJECT_ID}/locations/${REGION} i scala roles/iap.egressor powiązanie dla podmiotu zabezpieczeń agenta z zasadami uprawnień każdego serwera (odzwierciedlając semantykę gcloud add-iam-policy-binding).

Przypadek użycia 1. Bezwarunkowe przyznanie uprawnień ograniczone do określonych serwerów MCP

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID} \
  --mcp-filter "legacy-dms income-verification"

Przypadek użycia 2. Przyznanie warunkowe (CEL) ograniczone do konkretnego serwera MCP

Aby ograniczyć agenta do podzbioru narzędzi na jednym serwerze MCP, dołącz warunek uprawnień. Brama agenta publikuje atrybuty poszczególnych narzędzi, które interfejs IAP REQUEST_AUTHZ udostępnia CEL, w tym:

  • iap.googleapis.com/mcp.toolName
  • iap.googleapis.com/mcp.tool.isReadOnly
  • iap.googleapis.com/request.auth.type.

Ogranicz agenta do narzędzi tylko do odczytu na platformie corporate-email:

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID} \
  --mcp-filter "corporate-email" \
  --condition-expression "api.getAttribute('iap.googleapis.com/mcp.tool.isReadOnly', false) == true" \
  --condition-title "ReadOnlyToolsOnly" \
  --condition-description "Restrict ${AGENT_ID} to read-only tools on corporate-email"

Po uruchomieniu tego polecenia narzędzia do zapisu na corporate-email zwracają 403 PermissionDenied z IAP REQUEST_AUTHZ, a narzędzia tylko do odczytu nadal działają.

Sprawdzanie powiązań

Otwórz kartę Zasady, na której zobaczysz listę zasad utworzonych dla punktów końcowych i serwerów MCP.

Dodatkowe przypadki użycia:

Bezwarunkowe przyznanie dostępu na każdym serwerze MCP, ograniczone do jednego agenta

Uruchamiaj to polecenie po każdym ponownym wdrożeniu agenta. Jeśli nie ma filtra ani warunku, nazwany agent otrzymuje uprawnienia roles/iap.egressor na każdym serwerze MCP w rejestrze:

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID}

14. Testowanie agenta w konsoli Agent Platform

Konsola Agent Platform zawiera Playground, który umożliwia bezpośrednią rozmowę z wdrożonym agentem. To najszybszy sposób na przeprowadzenie testu dymnego wywołań narzędzi i sprawdzenie śladów przed połączeniem agenta z Gemini Enterprise.

  1. W konsoli Google Cloud otwórz stronę Wdrożenia platformy agentów.
  2. Jeśli chcesz zawęzić listę środowisk wykonawczych, użyj pola Filtr, a potem kliknij środowisko wykonawcze mortgage-agent.
  3. Otwórz kartę Playground.
  4. Wpisz prompta, aby porozmawiać z agentem:
I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Powinna zostać zwrócona odpowiedź z narzędzia do zarządzania dokumentami i narzędzia do weryfikacji dochodów. W odpowiedzi tej numery SSN powinny być zamaskowane. 5. Wpisz prompta z dodatkowym pytaniem:

Can you send a summary of this to my email jane@example.com

Agent powinien stwierdzić, że nie ma dostępu do narzędzia send_email, i odpowiednio zareagować.

Agent został wdrożony z instrumentacją OpenTelemetry, więc w Playgroundzie dostępne są 4 widoki panelu bocznego, między którymi możesz się przełączać w miarę odpowiadania agenta:

  • Ślad – pełne ślady rozmowy, w tym zakresy bramy agentów, IAP REQUEST_AUTHZ i Model Armor CONTENT_AUTHZ.
  • Wydarzenie – wykres wywołanych narzędzi i szczegóły zdarzenia w bieżącej turze.
  • Stan – stan sesji agenta oraz dane wejściowe i wyjściowe narzędzia.
  • Sesje – każda sesja rozpoczęta w tym czasie

15. Wymuszanie autoryzacji IAP

Po zweryfikowaniu wdrożenia możemy zaktualizować tryb egzekwowania IAP na null, aby wymusić stosowanie zasad. Otwórz terraform.tfvars i zmień tryb z DRY_RUN na null.

# IAP Enforcement Mode ("DRY_RUN" or null)
agent_gateway_iap_iam_enforcement_mode = null

Zastosuj zmianę.

terraform apply

Wróć do Playgroundu i spróbuj ponownie.

  1. W konsoli Google Cloud otwórz stronę Wdrożenia platformy agentów.
  2. Jeśli chcesz zawęzić listę środowisk wykonawczych, użyj pola Filtr, a potem kliknij środowisko wykonawcze mortgage-agent.
  3. Otwórz kartę Playground.
  4. Wpisz prompta, aby porozmawiać z agentem:
I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Powinna zostać zwrócona odpowiedź z narzędzia do zarządzania dokumentami i narzędzia do weryfikacji dochodów. W odpowiedzi tej numery SSN powinny być zamaskowane. 5. Wpisz prompta z dodatkowym pytaniem:

Can you send a summary of this to my email jane@example.com

Jeśli wszystko zostało skonfigurowane prawidłowo, agent powinien odpowiedzieć, że nie może wysłać e-maila z powodu zasad autoryzacji.

16. Konfigurowanie i testowanie Gemini Enterprise

Konfigurowanie Gemini Enterprise

Postępuj zgodnie z przewodnikiem wprowadzającym do Gemini Enterprise.

Rejestrowanie agenta ADK w Gemini Enterprise

Aby zarejestrować agenta w Gemini Enterprise, wykonaj te czynności.

  1. W konsoli Google Cloud otwórz stronę Gemini Enterprise.
  2. Wybierz aplikację Gemini Enterprise, w której jest zarejestrowany agent.
  3. Otwórz adres URL widoczny w sekcji Twoja aplikacja internetowa Gemini Enterprise jest gotowa.
  4. W menu po lewej stronie wybierz kartę Agent, aby otworzyć Galerię agentów.
  5. Wybierz Mortgage Assistant Agent i zacznij czatować.

Wypróbuj te same prompty w narzędziu Agent Runtime Playground:

Wstępny prompt:

I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Dodatkowe pytanie:

Can you send a summary of this to my email jane@example.com

Jeśli wrócisz do sekcji Wdrożenie agenta w konsoli, wybierz wdrożenie agenta i otwórz kartę śladów. Zobaczysz teraz agenta Gemini Assistant w zakresie pokazującym, że połączenie pochodzi z Gemini Enterprise.

17. Rozwiązywanie problemów i częste rozwiązania

  • terraform apply kończy się niepowodzeniem w przypadku bramy agenta z komunikatem „resource is being created and therefore can not be updated” – projekt najemcy bramy potrzebuje około 30 sekund na ustabilizowanie się, zanim będzie można dołączyć zasady autoryzacji. Zajmuje się tym moduł time_sleep.wait_for_gateway. Wystarczy ponownie uruchomić terraform apply.
  • Agent zgłasza „nie znaleziono serwerów MCP” lub uruchamia się tylko z narzędziami – sprawdź enable_agent_registry_endpoints = true w terraform.tfvars, a następnie:
    gcloud alpha agent-registry mcp-servers list \
  --project=${PROJECT_ID} --location=${REGION}
    Powinny się wyświetlić 3 wpisy (po jednym dla każdej usługi Cloud Run MCP). Jeśli lista jest pusta, sprawdź, czy usługi MCP są dostępne z poziomu sieci VPC i czy brama agenta wypełniła rejestr (robi to leniwie przy pierwszej liście narzędzi proxy).
  • Wywołania narzędzi zwracają błąd 403 PermissionDenied – ponownie uruchom scripts/grant_agent_mcp_egress.sh. Najczęstszą przyczyną jest zapomnienie o ponownym przyznaniu uprawnień po ponownym wdrożeniu agenta (reasoningEngines/ zmienia się przy każdym wdrożeniu).
  • skaffold run kończy się niepowodzeniem z komunikatem „permission denied on service account” (odmowa uprawnień na koncie usługi) – brakuje Ci roles/iam.serviceAccountUser. Ponownie uruchom przyznanie sobie uprawnień z poprzedniego kroku.
  • Błędy komunikacji DNS między bramą agenta a usługą równoważenia obciążenia MCP – sprawdź, czy agent_gateway_dns_peering_config.target_network dokładnie odpowiada projects/${PROJECT_ID}/global/networks/${VPC_NAME} i czy każdy wpis domains kończy się kropką.
  • terraform plan ciągle chce aktualizować tagi obrazów Cloud Run – nie powinno się to zdarzać z powodu reguły lifecycle { ignore_changes }. Jeśli tak jest, potwierdź, że nie edytowano mcp_services[*].image w terraform.tfvars po skaffold run.

18. Czyszczenie danych

Silnik wnioskowania nie jest zarządzany przez Terraform (tworzy go pakiet ADK SDK). Usuń go ręcznie:

gcloud beta ai reasoning-engines delete ${AGENT_ID} \
  --region=${REGION} --project=${PROJECT_ID}

Usuń wszystko, co zostało utworzone przez Terraform:

cd terraform
terraform destroy
cd ..

Jeśli publiczna strefa DNS została utworzona tylko na potrzeby tego ćwiczenia:

gcloud dns managed-zones delete agw-example-com

Na koniec usuń zasobnik stanu Terraform:

gcloud storage rm -r gs://${PROJECT_ID}-tfstate

19. Gratulacje

Gratulacje! Udało Ci się wdrożyć kompleksowe zarządzanie agentem ADK z wieloma narzędziami za pomocą bramy agenta. Działając jako scentralizowana platforma sterująca siecią, brama agentów umożliwiała ustanowienie bezpiecznej ścieżki ruchu wychodzącego do narzędzi prywatnych, egzekwowanie szczegółowych zasad uprawnień opartych na tożsamości za pomocą Identity-Aware Proxy oraz oczyszczanie interakcji z treściami przy użyciu zintegrowanych zabezpieczeń Model Armor.

Czego się dowiedziałeś(-aś)

  • Jak wdrożyć i skonfigurować bramę agenta jako centralną warstwę zarządzania ruchem wychodzącym z agenta do dowolnego miejsca.
  • Jak zintegrować rejestr agentów na potrzeby zarządzanego, dynamicznego wykrywania narzędzi w czasie działania.
  • Jak tworzyć i egzekwować zasady uprawnień oparte na narzędziach i warunkach, aby ściśle kontrolować ścieżki wykonywania agentów.
  • Jak wykorzystać rozszerzenia usługi Agent Gateway do stosowania zasad Model Armor, automatycznego przechwytywania i redagowania poufnych danych o aktywności agenta.

Dokumentacja