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

1. Wprowadzenie

Gemini Enterprise Agent Platform to otwarta platforma do tworzenia, skalowania i optymalizowania agentów AI klasy korporacyjnej oraz do zarządzania nimi na podstawie Twoich danych.

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

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

Informacje o bramie agentów

Brama agentów to komponent sieciowy pakietu Agent Governance na platformie. Działa jako punkt wejścia i wyjścia sieci dla wszystkich interakcji z agentem, co umożliwia administratorom ds. bezpieczeństwa 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 laboratorium 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 zabezpieczona 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 ułatwić korzystanie z tego ćwiczenia, 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 być właścicielem publicznej domeny 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 agentów na potrzeby dostępu opartego na tożsamości (IAM) i sprawdzania treści (Model Armor)
  • Śledzenie i weryfikowanie bezpiecznego kompleksowego wykonywania 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ę, przekazana 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 agentów – 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 Agent Runtime 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ę agentów 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 ćwiczenie jest przeznaczone dla inżynierów platform i inżynierów ds. bezpieczeństwa na wszystkich poziomach zaawansowania. Wypełnienie formularza 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 rozliczaniem, 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 bootstrap

Moduł podstawowy Terraform włącza około 30 interfejsów API przy pierwszym zastosowaniu, ale do 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 łańcuch narzędzi. W Cloud Shell większość z nich jest już dostępna. 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 pozostałej 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 demonstracyjnej:

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 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 menedżer certyfikatów mógł 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 – Certificate Manager weryfikuje 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 prywatna strefa 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. Jeśli 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 -out=tfplan
terraform apply tfplan

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
  • Rozszerzenia bramy agenta, załącznika sieci PSC-I, IAP i Model Armor, obie zasady autoryzacji oraz przyznanie roles/iap.egressor na poziomie projektu
  • Punkty końcowe rejestru agentów (Vertex AI, IAP, Discovery Engine itp.) oraz 3 serwery MCP (domyślnie zarejestrowane w *.run.app/mcp, a w przypadku włączonej sieci prywatnej w ./mcp).

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 agentów 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 agentów to zarządzana przez Google płaszczyzna zarządzania między Agent Runtime 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 – sprawdzane 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 zdarzenia dotyczące treści do rozszerzenia w celu ich oczyszczenia. Używane tutaj do wywoływania Model Armor, które sprawdza, czy nie doszło do wstrzykiwania promptów, obejścia zabezpieczeń, naruszenia zasad RAI i (opcjonalnie) naruszenia zasad ochrony informacji umożliwiających identyfikację osób (PII) za pomocą funkcji 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

sdpSettings.basicConfig Model Armor 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. Powiązanie IAP REQUEST_AUTHZ jest w rzeczywistości oceniane na poziomie poszczególnych serwerów MCP i silników wnioskowania. Jest ono przyznawane po wdrożeniu agenta i poznaniu jego identyfikatora. W tym celu wykonuje się krok „Przyznaj agentowi uprawnienia do ruchu wychodzącego z poszczególnych serwerów MCP” 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 ${PROJECT_ID}, ${REGION} i ${MCP_INGRESS} (adnotacja wejścia Cloud Run). Pobierz źródło MCP_INGRESS z danych wyjściowych Terraform, aby wyrenderowane manifesty były zsynchronizowane z enable_cloud_run_private_networking, a następnie wyrenderuj je 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

Wróć do głównego katalogu wersji demonstracyjnej:

cd ..

Zastąp wartości szablonu:

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

Przyznaj wszystkim agentom rolę ruchu wychodzącego IAP we wszystkich punktach końcowych zarejestrowanych w rejestrze. Agent potrzebuje dostępu do tych punktów końcowych, ponieważ podczas wdrażania musi uzyskać dostęp do github.com w celu pobrania pakietów, a następnie do różnych interfejsów API Google potrzebnych do wdrożenia.

./scripts/grant_agent_mcp_egress.sh --bind-all-agents --endpoints

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 \
  --mcp-invoker-sa=$(terraform -chdir=../../terraform output -raw agent_mcp_invoker_email) \
  --model-endpoint-location=global

Po zakończeniu działania skryptu skopiuj wydrukowany ciąg znaków reasoningEngines/ do powłoki (np. 4262292559201566720):

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

13. Przyznaj agentowi dostęp do wychodzących połączeń z 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. Więcej informacji znajdziesz w artykule Tworzenie zasad ruchu wychodzącego z agenta na serwer 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 konkretnych 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 językowi CEL, w tym:

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

Ogranicz dostęp 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 || api.getAttribute('iap.googleapis.com/mcp.toolName', '') == ''" \
  --condition-title "ReadOnlyToolsOnly" \
  --condition-description "Restrict ${AGENT_ID} to read-only tools on corporate-email"

Po uruchomieniu tego polecenia narzędzia do pisania na platformie corporate-email zwracają wartość 403 PermissionDenied z żądania autoryzacji IAP, 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. Bez filtra i bez warunku nazwany agent otrzymuje 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. Jest to najszybszy sposób na przetestowanie 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 tej odpowiedzi numery SSN powinny być zamaskowane. 5. Wpisz dodatkowe pytanie:

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

Agent będzie mógł wysłać e-maila, ponieważ zasady warunkowe nie są egzekwowane z powodu działania rozszerzenia IAP w trybie próbnym.

Ponieważ agent został wdrożony z instrumentacją OpenTelemetry, w Playgroundzie dostępne są 4 panele boczne, między którymi możesz się przełączać w miarę odpowiadania agenta:

  • Ślad – pełne ślady rozmowy, w tym zakresy bramy agenta, 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 tej odpowiedzi numery SSN powinny być zamaskowane. 5. Wpisz dodatkowe pytanie:

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 zarejestrowany jest 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, wybierzesz wdrożenie agenta i otworzysz kartę śladów, zobaczysz agenta Asystenta Gemini w zakresie pokazującym, że połączenie pochodzi z Gemini Enterprise.

17. Panel dostrzegalności

Panel debugowania autoryzacji zapewnia jeden widok ruchu wychodzącego agentów Agent Runtime.

Panel dostrzegalności

Panel zawiera te informacje:

  • Agent ➔ Punkt końcowy (odmowy 403)
  • Agent ➔ serwer MCP (odmowy 403)
  • Agent ➔ Agent (odmowy 403)
  • Niezarejestrowane blokady ruchu wychodzącego
  • Przegląd ruchu i tryb egzekwowania płatności w aplikacji
  • Odmowy IAM interfejsu API GCP

Każdy widżet wyświetla identyfikator agenta, żądany host, zarejestrowaną ścieżkę zasobu oraz informację, czy brama i IAP autoryzowały żądanie.

  • Niezarejestrowane blokady ruchu wychodzącego – ten widżet wyodrębnia ruch, który został zablokowany przez bramę agenta, ponieważ nazwa hosta docelowego nie istnieje w rejestrze agentów. Ponieważ serwer proxy bramy blokuje te żądania, zanim dotrą do IAP, nie ma logów kontrolnych IAP dla tych wpisów.
  • Przegląd ruchu i tryb wymuszania IAP – ten widżet zawiera tabelę ze wszystkimi wzorcami ruchu. Co ważne, zawiera on stan testu IAP, dzięki czemu użytkownicy mogą sprawdzić, czy zasady IAP aktywnie blokują ruch, czy tylko go obserwują.
  • Odmowy IAM interfejsu GCP API – ten widżet przeszukuje standardowe logi kontrolne Cloud (cloudaudit.googleapis.com), aby wykrywać podstawowe błędy uprawnień interfejsu Google Cloud API w przypadku agentów.

Ten panel znajdziesz w konsoli Cloud: Monitoring > Dashboards > Agent Platform: Authorization Debugging

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

Debugowanie z pomocą AI za pomocą interfejsu wiersza poleceń Gemini

Aby rozwiązywać problemy, możesz użyć agent-platform-debuggerumiejętności w interfejsie wiersza poleceń Gemini. Pakiet umiejętności zawiera specjalistyczną wiedzę na potrzeby debugowania z pomocą AI. Interfejs wiersza poleceń Gemini traktuje .agents/skills/ jako alias najwyższego rzędu dla .gemini/skills/ w zakresie obszaru roboczego, więc możesz bezpośrednio korzystać z umiejętności. Aby użyć tej umiejętności w repozytorium Codelab:

Przejdź do katalogu repozytorium i uruchom interfejs wiersza poleceń Gemini:

cd /path/to/cloud-networking-solutions/demos/agent-gateway
gemini

Gdy pojawi się odpowiedni monit, zaufaj obszarowi roboczemu (umiejętności w zakresie obszaru roboczego są wczytywane tylko z zaufanych folderów). Sprawdź, czy umiejętność została wczytana:

/skills list

Na liście powinna pojawić się pozycja agent-platform-debugger. Jeśli go nie ma, ponownie załaduj umiejętności:

/skills reload

Wskazówki dotyczące rozwiązywania problemów

  • 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, zanim będzie można do niego 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 potem:
    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 agentów 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 DNS w komunikacji 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.

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

20. 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 za pomocą zintegrowanych zabezpieczeń Model Armor.

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

  • Jak wdrożyć i skonfigurować bramę agentów jako centralną warstwę zarządzania ruchem wychodzącym z agenta do dowolnego miejsca.
  • Jak zintegrować rejestr agentów w celu zarządzanego, dynamicznego wykrywania narzędzi w czasie działania.
  • Jak tworzyć i egzekwować zasady uprawnień dotyczące poszczególnych narzędzi i warunków, aby ściśle kontrolować ścieżki wykonywania agenta.
  • Jak wykorzystać rozszerzenia usługi Brama agentów do stosowania zasad Model Armor, automatycznego przechwytywania i usuwania poufnych danych o ruchu agenta.

Dokumentacja