Gemini Enterprise Agent Platform의 에이전트 게이트웨이를 사용한 에이전트 워크로드 관리

1. 소개

Gemini Enterprise Agent Platform은 데이터를 기반으로 그라운딩된 엔터프라이즈급 AI 에이전트를 빌드, 확장, 제어, 최적화할 수 있는 개방형 플랫폼입니다.

에이전트 런타임은 Google Cloud 내에서 안전하게 에이전트를 실행하기 위한 관리형 실행 환경을 제공합니다. 여기에는 오픈소스 에이전트 개발 키트 (ADK)로 빌드된 에이전트가 포함됩니다.

이 Codelab에서는 이러한 핵심 빌딩 블록을 사용하여 Gemini Enterprise에서 사용자가 시작한 에이전트가 내부 도구에 안전하게 연결될 때 이를 관리하는 방법을 살펴봅니다.

Agent Gateway 정보

Agent Gateway는 플랫폼의 Agent Governance 제품군의 네트워킹 구성요소입니다. 모든 에이전트 상호작용의 네트워크 진입점 및 종료점 역할을 하므로 보안 관리자는 개발자가 복잡한 네트워킹 기본 요소를 관리하지 않아도 중앙 집중식 거버넌스를 적용할 수 있습니다.

이 기능은 두 가지 주요 관리 액세스 경로를 지원합니다.

  • 클라이언트-에이전트 (인그레스): 외부 클라이언트 (예: Cursor 또는 Gemini CLI)와 에이전트 간의 통신을 보호합니다.
  • 에이전트-어디서나 (이그레스): Google Cloud에서 실행되는 에이전트와 어디서나 실행되는 서버, 도구 또는 API 간의 통신을 보호합니다.

이 Codelab에서는 에이전트-어디로든 (egress) 모드에 중점을 둡니다.

에이전트 게이트웨이를 사용한 액세스 제어

보안 정책을 적용하기 위해 Agent Gateway는 나머지 생태계와 긴밀하게 통합됩니다.

  • 에이전트 레지스트리: 승인된 에이전트 및 도구 (서드 파티 MCP 서버 포함)의 중앙 라이브러리입니다.
  • 상담사 ID: 모든 상담사에 대한 추적 가능한 고유한 페르소나로, 엔드 투 엔드 mTLS로 자동 보안 처리됩니다.
  • Identity-Aware Proxy (IAP) 및 IAM: 특정 도구에 대한 호출을 허용하기 전에 세부적인 IAM 권한에 대해 에이전트의 ID를 검증하는 기본 시행 레이어입니다.
  • Model Armor: Service Extensions를 통해 통합되어 콘텐츠를 정리하고 프롬프트 인젝션 공격이나 데이터 유출로부터 보호하는 AI 보안 가이드라인입니다.

배포 모드 (Cloud Run의 공개 네트워킹과 비공개 네트워킹)

이 Codelab에 액세스하려면 Cloud Run에 배포된 내부 도구 (MCP 서버)에 대해 다음 두 가지 네트워킹 경로 중에서 선택하면 됩니다.

  1. 기본값 (공개 인그레스): MCP 서버가 공개 호스트 이름 (ingress=all)으로 Cloud Run에 배포됩니다. 트래픽은 표준 *.run.app URL을 통해 에이전트에서 도구로 라우팅됩니다. 이 방법은 맞춤 DNS 도메인이 필요하지 않으며 거버넌스 개념을 가장 빠르게 학습할 수 있습니다.
  2. 보안 (비공개 네트워킹): 선택사항인 완전 비공개 아키텍처입니다. MCP 서버는 제한 (ingress=internal-and-cloud-load-balancing)되고 서버리스 NEG가 있는 내부 애플리케이션 부하 분산기를 통해 노출됩니다. 이렇게 하려면 Google 관리형 인증서를 프로비저닝할 공개 DNS 도메인을 소유해야 합니다.

Terraform을 구성할 때 원하는 경로를 선택합니다.

Cloud Run의 네트워크 엔드포인트 인그레스에 대해 자세히 알아보려면 문서를 참고하세요.

실습할 내용

  • Terraform을 사용하여 핵심 인프라 스택 프로비저닝
  • Cloud Run에서 내부 도구를 MCP 서버로 빌드 및 배포
  • PSC 인터페이스 이그레스를 사용하여 Agent Runtime에 ADK 에이전트 배포
  • ID 기반 액세스 (IAM) 및 콘텐츠 검열 (Model Armor)을 위한 에이전트 게이트웨이 서비스 확장 프로그램 구성
  • 에이전트의 안전한 엔드 투 엔드 실행 추적 및 검증

필요한 항목

  • 웹브라우저(예: Chrome)
  • 결제가 사용 설정되고 소유자 액세스 권한이 있는 Google Cloud 프로젝트
  • 조직 수준 IAM 권한 (코드랩에서 조직 범위 역할 부여)
  • Cloud DNS에 위임된 관리형 공개 인증서의 도메인
  • Terraform, gcloud, 기본 Google Cloud 네트워킹에 대한 이해

Codelab 토폴로지

엔드 투 엔드 아키텍처: Gemini Enterprise에서 Agent Runtime, Agent Gateway, Cloud Run의 MCP 서버로

이 Codelab에서는 세 가지 내부 도구와 안전하게 통신하는 엔드 투 엔드 모기지 심사 에이전트를 배포합니다.

먼저 에이전트 게이트웨이로 구성된 VPC와 내부 애플리케이션 부하 분산기를 비롯한 기본 네트워킹을 프로비저닝합니다. 다음으로 모델 컨텍스트 프로토콜 (MCP) 서버 3개를 Cloud Run에 배포합니다. 다음은 내부 독점 도구로 작동합니다.

  • 문서 관리 (legacy-dms)
  • 회사 이메일 (corporate-email)
  • 수입 확인 (income-verification)

도구가 준비되면 ADK로 빌드된 Mortgage Assistant (mortgage-agent)를 Agent Runtime에 배포합니다. 비공개 이그레스를 위해 PSC 인터페이스를 사용하고 에이전트 레지스트리를 통해 런타임 도구 검색을 사용 설정하도록 이 에이전트를 구성합니다.

흐름을 보호하려면 서비스 확장 프로그램 두 개로 Agent Gateway를 구성합니다. 먼저 REQUEST_AUTHZ 확장 프로그램이 도구별 IAM 정책에 대해 에이전트 ID를 확인하여 에이전트가 승인된 도구에만 액세스하도록 합니다. 두 번째로 Model Armor를 사용하는 CONTENT_AUTHZ 확장 프로그램이 에이전트의 프롬프트와 응답을 검사합니다.

마지막으로 Gemini Enterprise에 에이전트를 등록하고, 최종 사용자로 모기지 인수 작업을 트리거하고, Cloud Trace를 사용하여 안전하고 관리되는 실행을 확인합니다.

이 Codelab은 모든 수준의 플랫폼 및 보안 엔지니어를 대상으로 합니다. 완료하는 데 약 100분이 소요될 것으로 예상됩니다.

2. 시작하기 전에

프로젝트 생성 및 인증

결제가 사용 설정된 새 GCP 프로젝트를 만들거나 기존 프로젝트를 재사용하고 Cloud Shell 또는 로컬 머신을 인증합니다.

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

부트스트랩 API 사용 설정

Terraform의 파운데이션 모듈은 첫 번째 적용 시 약 30개의 API를 사용 설정하지만 terraform init 및 GCS 상태 버킷에는 작은 부트스트랩 세트가 필요합니다.

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

필수 도구 설치

도구 모음을 설치합니다. Cloud Shell에서는 이러한 항목이 대부분 이미 제공됩니다. 워크스테이션에서는 다음을 실행하세요.

# 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

Terraform >= 1.12.2, Python 3.12 이상, Google Cloud SDK (gcloud)도 필요합니다.

환경 변수 설정하기

Codelab의 나머지 부분에서는 이러한 항목이 셸에 내보내진 것으로 가정합니다.

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"

모든 변수가 올바르게 채워졌는지 확인합니다. 3개의 값이 반환되어야 합니다.

echo $PROJECT_ID  
echo $PROJECT_NUMBER
echo $ORG_ID

조직 ID가 자동으로 채워지지 않으면 직접 찾아 설정할 수 있습니다.

gcloud organizations list
export ORG_ID=ID_FROM_OUTPUT

3. 저장소 복제 

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

데모 디렉터리의 내용을 간단히 살펴보겠습니다.

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. Terraform 상태 버킷 및 백엔드 구성 만들기

원격 상태를 저장할 GCS 버킷을 만든 다음 백엔드 템플릿을 복사합니다.

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

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

terraform/backend.conf를 사용자 값으로 수정합니다.

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

5. (선택사항) 공개 Cloud DNS 영역 만들기

이 실습에서 Cloud Run의 수신 구성은 기본적으로 all로 설정되어 있으며 에이전트 레지스트리는 각 MCP 서버를 공개 *.run.app URL에 등록합니다. 추가 DNS, 인증서 또는 부하 분산기가 필요하지 않습니다. 비공개 네트워킹 (내부 애플리케이션 LB 뒤에 있는 Cloud Run)으로 전환하려면 인증서 관리자가 LB 인증서를 검증할 수 있도록 공개 Cloud DNS 영역도 필요합니다.ingress = internal-and-cloud-load-balancing

비공개 네트워킹의 개략적인 흐름

비공개 네트워킹 옵션의 개략적인 흐름

비공개 네트워킹 방식을 사용하려면 다음 단계를 따르세요.

  1. 공개 Cloud DNS 영역을 만듭니다. 인증서 관리자는 CNAME을 작성하여 리전 관리형 인증서를 검증합니다.
gcloud dns managed-zones create agw-example-com \
  --dns-name="${DOMAIN_NAME}." \
  --description="Public zone for ${DOMAIN_NAME}" \
  --visibility=public

mcp.${DOMAIN_NAME}의 해당 비공개 영역 (MCP 내부 LB 및 Agent Runtime의 DNS 피어링에서 사용)은 Terraform에 의해 자동으로 생성되므로 직접 만들 필요가 없습니다. 비공개 네트워킹이 사용 중지되면 공개 영역과 비공개 영역이 모두 프로비저닝되지 않습니다.

6. Terraform 변수 구성

예시 tfvars를 복사하여 수정합니다.

cp terraform/example.tfvars terraform/terraform.tfvars

enable_cloud_run_private_networking로 관리되는 두 가지 데모 경로가 있습니다.

기본 경로: 공개 인그레스가 있는 Cloud Run

가장 간단한 설정: 기본 경로의 경우 terraform.tfvars에서 세 값만 수정하면 됩니다. 파일의 다른 모든 변수에는 이미 데모에 적합한 기본값이 있습니다.

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

비공개 네트워킹 (선택사항)

enable_cloud_run_private_networking = true를 설정하고 아래 변수를 추가하여 전체 보안 스택을 프로비저닝합니다.

  • 내부 애플리케이션 LB
  • Google 관리 인증서
  • ingress = internal-and-cloud-load-balancing를 사용하는 Cloud Run
  • 에이전트 게이트웨이 DNS 피어링입니다.
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. Terraform으로 인프라 배포

초기화, 검토, 적용:

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

terraform apply는 기본 경로에 약 40개의 리소스를 프로비저닝하고 새 프로젝트에서 8~10분이 걸립니다 (enable_cloud_run_private_networking = true의 경우 약 60개의 리소스 / 15~20분). 다음을 만듭니다.

  • 프로젝트 기반 (API, 서비스 ID, 할당량)
  • VPC, 서브넷 (기본, 프록시 전용, PSC, PSC 인터페이스, Agent Gateway 공동 배치), Cloud NAT, 방화벽 규칙
  • Cloud Run 이미지용 Artifact Registry 저장소
  • Cloud Run 서비스 3개 + 서비스별 런타임 SA (인그레스 = 기본적으로 all, 비공개 네트워킹이 사용 설정된 경우 internal-and-cloud-load-balancing)
  • Model Armor 템플릿 + IAM
  • 에이전트 게이트웨이, PSC-I 네트워크 연결, IAP 및 Model Armor 확장 프로그램, 두 승인 정책, 프로젝트 수준 roles/iap.egressor 부여
  • 에이전트 레지스트리 엔드포인트 (Vertex AI, IAP, Discovery Engine 등)와 세 개의 MCP 서버 (기본적으로 *.run.app/mcp에 등록됨, 비공개 네트워킹이 사용 설정된 경우 ./mcp에 등록됨)

enable_cloud_run_private_networking = true인 경우에만:

  • 서버리스 NEG (URL 마스크 라우팅) + 비공개 DNS A 레코드가 있는 내부 리전 애플리케이션 LB
  • VPC에 연결된 MCP 비공개 DNS 영역 (mcp..)
  • 공개 DNS 영역 모듈 (인증서 관리자 DNS 승인) + 리전별 Google 관리형 인증서
  • PSC 인터페이스 DNS 영역 (확인할 비공개 호스트 이름이 없으면 고아가 되므로 마스터 플래그로도 관리됨)
  • mcp..의 Agent Gateway DNS 피어링 (자동으로 앞에 추가됨)

8. 에이전트 레지스트리 엔드포인트 검사

Agent Registry는 에이전트가 런타임에 검색하는 서비스 (Google API 및 자체 MCP 서버)의 프로젝트별 카탈로그입니다. 모기지 에이전트는 시작 시 이를 읽고 도구를 동적으로 바인딩합니다. MCP URL은 에이전트 코드나 배포 명령에 포함되지 않습니다.

엔드포인트

Terraform이 사용자를 대신하여 실행한 작업: agent_registry_google_apis의 각 Google API에 대해 5가지 변형 (전역, mTLS 전역, 리전, 리전 mTLS, 리전 REP)을 등록했습니다. 예를 들어 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)"