1. 소개
이 Codelab에서는 원격 Google Cloud 모델 컨텍스트 프로토콜 (MCP) 서버에 액세스하는 AI 에이전트의 에이전트 게이트웨이 이그레스 거버넌스를 살펴봅니다.
독립형 챗봇부터 멀티 에이전트 워크플로가 있는 자율 시스템에 이르기까지 AI 앱은 외부 도구를 동적으로 호출할 수 있습니다. 데이터베이스를 쿼리하고, 웹 콘텐츠를 가져오고, 작업을 실행할 수 있는 제어된 액세스 권한을 에이전트에게 제공하는 것은 안전하고 생산적인 에이전트를 위해 필수적입니다. 하지만 엔터프라이즈 환경에서는 에이전트 도구 실행을 보호하는 것이 어렵습니다. 에이전트가 직접 네트워크 액세스 권한을 보유한 경우 프롬프트 인젝션 공격이나 모델 할루시네이션으로 인해 에이전트가 민감한 정보를 유출하거나 파괴적인 명령어를 실행할 수 있습니다.
에이전트 게이트웨이는 자율 에이전트를 대규모로 관리하기 위해 Agent Platform 아키텍처에 직접 통합된 중앙 집중식 제로 트러스트 시행 지점을 제공합니다. 각 애플리케이션 또는 에이전트 코드에 고유한 맞춤 구현에 의존하는 대신 Agent Gateway는 플랫폼 수준에서 적용되는 네트워크 라우팅, 에이전트 거버넌스, 런타임 보안을 제공합니다.
Agent Gateway가 이그레스 (agent-to-anywhere) 모드로 작동하면 게이트웨이를 사용하도록 구성된 에이전트의 모든 아웃바운드 요청을 프록시합니다. 각 에이전트 워크로드 요청은 고유한 에이전트 ID를 사용하여 인증되고 Identity-Aware Proxy (IAP) 정책을 사용하여 승인됩니다. MCP 도구 호출은 정책 시행을 위해 동적으로 디코딩되고 검사됩니다. 보안 관리자는 세부적인 권한을 중앙에서 적용하여 에이전트가 승인된 엔드포인트와 메서드만 호출할 수 있도록 할 수 있습니다.
빌드할 항목
- 이그레스의 Agent Gateway (agent-to-anywhere) 모드
- IAP (Identity-Aware Proxy) 승인 확장 프로그램
- 에이전트 ID가 있는 Agent Runtime ADK 에이전트
- Google API 및 MCP 엔드포인트가 있는 에이전트 레지스트리
- IAM 액세스 제어를 사용하는 승인 정책
- MCP를 사용하여 쿼리할 BigQuery 데이터 세트
그림 1. Codelab 아키텍처
학습 내용
- 구조화된 구성 시퀀스에서 Agent Gateway를 배포하는 방법
- 승인 정책을 테스트 실행 모드에서 시행 모드로 전환하는 방법
- 에이전트 레지스트리에 Google API 엔드포인트 및 MCP 서버를 등록하는 방법
- Agent Gateway 로그를 감사하여 이그레스 거버넌스를 검증하는 방법
필요한 항목
- 결제가 사용 설정된 Google Cloud 프로젝트
- 네트워킹 서비스, BigQuery 데이터 세트, Agent Platform 리소스를 프로비저닝하는 IAM 권한
- Google Cloud CLI (
gcloud및bq구성요소)가 설치된 POSIX 호환 셸 (bash또는zsh) - 명령줄 도구:
git,curl,jq(JSON 프로세서), Python 3,uv(Python 패키지 관리자)
2. 개념
배포 시퀀스
거버넌스 제어를 사용하여 Agent Gateway를 배포할 때는 에이전트가 초기화 시 필요한 리소스에 액세스할 수 있고 네트워크 요청이 성공할 수 있도록 구조화된 구성 시퀀스를 따라야 합니다.
이 Codelab에서는 다음 배포 시퀀스를 사용합니다.
- 드라이런 모드로 시작: 게이트웨이가 완전히 프로비저닝되기 전에 아웃바운드 통화를 게이트웨이로 라우팅하도록 에이전트 런타임이 구성된 경우 워크로드가 초기화되지 않습니다. 먼저
DRY_RUN모드에서 게이트웨이 승인 확장 프로그램을 구성하면 상담사 트래픽이 게이트웨이에 도착할 때 요청이 삭제되지 않습니다. - 모든 서비스 등록: Agent Gateway를 사용하는 모든 에이전트, MCP 서버, 엔드포인트는 에이전트 레지스트리에 등록되어야 합니다. 등록되지 않은 소스 또는 대상에 대한 요청은 거부됩니다. Agent Runtime 및 Google MCP 서버에 배포된 에이전트는 자동으로 등록됩니다. Google API 엔드포인트 또는 커스텀 MCP 서버는 수동으로 등록해야 합니다.
- 승인 정책 적용: 승인 정책은 등록된 에이전트가 에이전트 ID 주 구성원에게
roles/iap.egressor역할을 부여하고 이를 타겟 레지스트리 리소스에 바인딩하여 에이전트 구성요소에 액세스하도록 허용하는 데 사용됩니다. 테스트 실행 모드를 사용하여 에이전트 동작을 평가한 다음 게이트웨이를 통해 선택한 이그레스 트래픽을 허용하는 정책을 정의합니다. 정책이 마련되면ENFORCED모드로 전환하여 게이트웨이가 거버넌스 정책을 적극적으로 시행하도록 합니다.
그림 2. 배포 시퀀스
이그레스 라우팅 토폴로지
게이트웨이는 일반적으로 백엔드 서비스로의 인바운드 트래픽 (인그레스)을 관리합니다. 이그레스 (agent-to-anywhere) 모드로 작동하는 Agent Gateway는 에이전트형 워크로드의 중앙화된 제로 트러스트 아웃바운드 프록시 역할을 합니다.
AI 앱 또는 에이전트형 워크로드가 외부 도구 또는 API를 호출하려고 하면 아웃바운드 요청이 Agent Gateway에 의해 가로채지고 거버넌스 정책에 따라 평가된 후 대상으로 라우팅됩니다.
- 비공개 네트워크 (VPC): 하이브리드 연결을 통해 연결할 수 있는 내부 엔터프라이즈 API, 마이크로서비스, 비공개 VPC 내에 호스팅된 데이터베이스, 온프레미스 또는 크로스 클라우드 네트워크를 타겟팅하는 아웃바운드 트래픽입니다.
- 외부 네트워크 (인터넷): 서드 파티 웹 서비스, SaaS API 또는 공개 엔드포인트를 타겟팅하는 아웃바운드 트래픽입니다.
- AI 서비스 및 에이전트 플랫폼: 관리형 Google Cloud API, 기본 모델, Google MCP 엔드포인트 (예: BigQuery), 플랫폼 거버넌스 서비스 (에이전트 레지스트리 및 IAP 정책)를 타겟팅하는 아웃바운드 트래픽입니다.
그림 3. 에이전트 게이트웨이 이그레스 라우팅 토폴로지
이 Codelab에서는 BigQuery의 원격 Google MCP 서버 엔드포인트를 타겟팅하는 에이전트 런타임의 맞춤 에이전트에서 발생하는 아웃바운드 트래픽에 중점을 둡니다.
3. 설정
필요한 IAM 역할
이 Codelab에서 리소스를 만들려면 다음 역할이 필요합니다.
카테고리 | 필수 IAM 역할 (ID) | 설명 |
API 관리 |
| Google Cloud API 서비스 사용 설정 |
네트워킹 및 게이트웨이 |
| 에이전트 게이트웨이 프로비저닝 |
Service Extensions |
| 라우팅 확장 프로그램 구성 |
네트워크 보안 |
| 승인 정책 배포 |
에이전트 레지스트리 |
| 카탈로그 허용 호스트 |
Vertex AI 및 에이전트 |
| Agent Runtime 워크로드 배포 |
이그레스 정책 |
|
|
BigQuery |
| 스키마 및 테스트 데이터 세트 설정 |
Cloud Storage |
| 배포 스테이징 버킷 관리 |
로그 및 감사 |
| 트레이스 및 감사 로그 검사 |
또는 roles/admin와 같은 광범위한 기본 역할이나 기존 역할 roles/owner를 사용합니다.
프로젝트에 액세스
이 Codelab에서는 단일 Google Cloud 프로젝트를 사용합니다. 구성 단계에서는 gcloud CLI 및 Linux 셸 명령어를 사용합니다.
먼저 Google Cloud 프로젝트 명령줄에 액세스합니다.
shell.cloud.google.com의 Cloud ShellgcloudCLI가 설치된 로컬 터미널
프로젝트 ID 설정
gcloud config set project SET_YOUR_PROJECT_ID_HERE
세션 인증
# login to gcloud cli
gcloud auth login
# login for gcloud api
gcloud auth application-default login
셸 환경 변수 설정
# 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
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
이것으로 설정 부분이 마무리되었습니다. 다음은 게이트웨이 섹션입니다.
4. 게이트웨이
액세스 제어를 적용하기 전에 Agent Gateway를 배포하고 DRY_RUN 모드에서 승인 확장 프로그램을 구성합니다. 이렇게 하면 감사 목적으로 평가 결과를 로깅하는 동안 아웃바운드 도구 호출이 성공할 수 있습니다.
여기서 에이전트 게이트웨이는 리전별 Agent Runtime 리소스를 지원하기 위해 리전별 레지스트리를 사용합니다.
게이트웨이 만들기
# 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}
이것으로 게이트웨이 부분이 마무리되었습니다. 다음으로 승인 섹션으로 이동합니다.
5. 승인
Identity-Aware Proxy (IAP)용 Agent Gateway 승인 확장 프로그램은 모든 Agent Platform 통신의 승인 결정을 위임하는 데 사용되는 Service Extensions의 한 유형입니다.
- 위임 흐름: 에이전트가 외부 엔드포인트 또는 MCP 서버를 호출하려고 하면 요청이 Agent Gateway로 라우팅됩니다. 게이트웨이는 로컬에서 액세스를 평가하는 대신 승인 확장 프로그램을 사용하여 IAP 평가 서비스에 콜아웃을 전송합니다. IAP는 Agent Registry의 타겟 리소스 IAM 정책에 대해 에이전트 (SPIFFE 기반) ID를 평가합니다. IAP는
ALLOW또는DENY결정을 게이트웨이에 다시 반환하며, 게이트웨이는 트래픽을 전달하거나 HTTP403 Forbidden상태 코드로 차단합니다. - 강제 적용 모드:
DRY_RUN모드에서 IAP는 요청을 평가하고 트래픽을 차단하지 않고 Cloud Logging에 결정을 로깅합니다.ENFORCE모드에서는 승인되지 않은 에이전트의 요청이나 등록되지 않은 타겟에 대한 요청이 즉시 차단됩니다. - 바인딩 레이어: 서비스 확장 프로그램은
REQUEST_AUTHZ프로필로 구성된 승인 정책을 사용하여 Agent Gateway에 연결됩니다.
승인 확장 프로그램
승인 확장 프로그램 만들기
# 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}
승인 정책
승인 정책은 보안 제공업체 (IAP)를 타겟 게이트웨이 리소스에 바인딩하고 인터셉션 프로필 (REQUEST_AUTHZ)을 지정합니다.
승인 정책 만들기
# 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}
이것으로 승인 부분이 마무리되었습니다. 다음으로 코드베이스 섹션으로 이동합니다.
6. 코드베이스
이 Codelab에 사용되는 에이전트 코드, BigQuery 데이터 세트, 등록 스크립트는 원격 Google Cloud GitHub 저장소에서 유지관리됩니다. 다음 단계에서는 저장소를 로컬로 클론하고, 필요한 파일을 현재 작업 디렉터리 구조에 복사한 후, 불필요한 임시 파일을 정리합니다.
패키징된 에이전트 애플리케이션 코드와 종속 항목 아티팩트를 업로드, 빌드, 배포하기 위해 Agent Runtime용 스토리지 스테이징 버킷이 생성됩니다.
원격 아티팩트 가져오기
# 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
BigQuery 데이터 세트 만들기
# create bq dataset schema and load data
bq --project_id=${PROJ_ID} query \
--use_legacy_sql=false < agent-dj/setup.sql
스테이징 버킷 만들기
# 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)"
이것으로 코드베이스 부분이 마무리되었습니다. 다음은 레지스트리 섹션입니다.
7. 레지스트리
Agent Registry는 AI 생태계의 모든 에이전트, MCP 서버, 엔드포인트 (API)의 중앙 집중식 인벤토리입니다. 또한 AI 애플리케이션에서 사용할 수 있는 다른 등록된 도구와 서비스를 나열, 검색, 탐색하는 데 사용할 수 있는 카탈로그이기도 합니다. 에이전트 게이트웨이 이그레스 (agent-to-anywhere) 모드는 레지스트리 데이터 모델을 거버넌스 프레임워크로 사용하여 이그레스 액세스 제어를 적용합니다. 주 구성원 호출 에이전트에 대한 IAM 역할 부여는 레지스트리 리소스에 바인딩된 정책에 대해 확인됩니다.
환경을 부트스트랩하고 다양한 Google API 및 서비스를 사용하는 상담사를 지원하기 위해 스크립트를 사용하여 endpoints/googleapis.txt의 호스트 이름과 위치를 사용하여 일반적인 API 엔드포인트 집합을 빠르게 등록합니다.
엔드포인트 등록
# run python script to register google api endpoints
python3 endpoints/register_endpoints.py \
--multi-region=${MREGION} \
--region=${REGION} \
--mtls-endpoints=include
엔드포인트 확인
# 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)"
이로써 레지스트리 부분이 마무리되었습니다. 다음은 런타임 섹션입니다.
8. 런타임
Agent Runtime에 배포된 agent-dj ADK 에이전트는 Agent Platform과 통합하기 위해 배포 스크립트에서 다음 설정으로 구성됩니다.
"identity_type": types.IdentityType.AGENT_IDENTITY를 사용하여 에이전트의 고유한 SPIFFE 기반 보안 주체 ID를 프로비저닝합니다."agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } }를 사용하여 모든 아웃바운드 에이전트 시작 트래픽을 정책 평가 및 시행을 위해 에이전트 게이트웨이로 전달
에이전트 배포
# 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
배포 주요 지표 가져오기
# 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}
레지스트리 항목 확인
# 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'
게이트웨이 구성 확인
# 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}'
리소스에 대한 에이전트 IAM 역할 부여
리소스에 대한 IAM 역할 부여를 통해 에이전트 주 구성원 ID가 BigQuery, MCP 도구 (Google API용), 기타 필수 AI 플랫폼 서비스에 액세스할 수 있습니다. 이러한 정책은 리소스 수준에서 IAM을 사용하여 적용됩니다.
# 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"
리소스의 에이전트 IAM 역할 확인
# 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)"
이것으로 런타임 부분이 마무리되었습니다. 다음은 정책 섹션입니다.
9. 정책
에이전트 거버넌스 승인 정책은 Agent Gateway를 통해 AI 에이전트에서 목적지 (예: BigQuery용 Google Cloud MCP 서버 엔드포인트)로 트래픽을 허용합니다. 트래픽이 대상에 도달하면 일반 IAM 권한이 데이터 액세스를 승인합니다 (이전 섹션에서 사용 설정됨).
에이전트 게이트웨이 이그레스에 대한 IAM 역할 부여를 사용하면 에이전트 주 구성원 ID가 에이전트 게이트웨이를 통해 등록된 대상 리소스에 액세스할 수 있는 액세스 정책이 사용 설정됩니다. 정책은 Agent Gateway 수준에서 적용되며 IAP (Identity-Aware Proxy) IAM 정책을 사용하여 검증됩니다.
에이전트 게이트웨이 이그레스에 대한 에이전트 IAM 역할 부여
에이전트 게이트웨이는 수신 요청을 확인하여 호출 에이전트 ID에 타겟 리소스에 대한 iap.webServiceVersions.egressViaIAP 권한 (roles/iap.egressor 역할에 의해 부여됨)이 있는지 확인합니다.
선택한 대상 리소스에 대한 에이전트 ID 또는 Agent Runtime 주 구성원 집합에 roles/iap.egressor 권한을 부여하면 이 이그레스 트래픽이 허용됩니다. 이 Codelab에서는 역할이 주 구성원 set에 적용되어 프로젝트의 모든 Agent Runtime 에이전트 ID에 권한을 부여합니다.
IAM 정책은 에이전트 레지스트리 데이터 모델에 정의된 대로 대상 리소스에 바인딩됩니다. iap_web/agentRegistry 리소스는 IAM 계층 구조의 '레지스트리 전체' 수준을 나타냅니다. 여기서 agentRegistry은 agents, mcpServers, endpoints의 개별 하위 리소스의 상위 요소 역할을 합니다. 이 Codelab에서는 IAM 정책이 레지스트리 수준에 바인딩되어 모든 하위 리소스에 권한이 적용됩니다.
IAP 지역 레지스트리 IAM 정책 구성
# 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}
정책 부분이 끝났습니다. 다음은 감사 섹션입니다.
10. 감사
Agent Gateway 승인 확장 프로그램이 DRY_RUN 모드로 작동하고 있습니다. 아웃바운드 요청은 관찰되고 로깅되지만 차단되지는 않습니다.
에이전트 쿼리 테스트
브라우저 창을 열어 Google Cloud 콘솔 UI로 이동하고 다음으로 이동합니다.
- Agent Platform → Agents → Deployments →
agent-dj - Playground 탭을 선택합니다.
또는 이 터미널 명령어를 에코하고 링크를 클릭하여 에이전트 그라운드로 이동합니다.
# playground
echo "https://console.cloud.google.com/agent-platform/runtimes/locations/${REGION}/agent-engines/${RE_ENGINE_ID}/playground?project=${PROJ_ID}"
테스트 쿼리를 제출합니다.
How many DJs do we have on file?What is the phone number of DJ Cosmopup?
질문에서 유효한 대답 (예: '파일에 DJ가 12명 있습니다')이 반환되는지 확인합니다.
감사 로그 분석
로그를 확인하고 테스트 실행 정책 평가를 검사합니다.
# 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
감사 부분이 끝났습니다. 다음은 시행 섹션입니다.
11. 적용
상담사는 DRY_RUN 모드에서 게이트웨이를 통해 요청을 성공적으로 수행할 수 있었습니다. 승인 정책을 업데이트하여 Agent Gateway IAP 승인 확장 프로그램을 ENFORCE 모드로 전환합니다.
승인 확장 프로그램 업데이트
# 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}
승인 정책 업데이트
# 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}
시행 확인
콘솔 UI에서 에이전트 Playground로 돌아갑니다.
추가 테스트 질문을 제출하세요.
What DJ Fishfry's credit card number?
Gemini 파운데이션 모델 (${REGION}-aiplatform.googleapis.com/...) 및 MCP 서버 엔드포인트 (bigquery.googleapis.com/mcp)에 대한 에이전트 요청이 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)"
차단된 요청이 없는지 확인합니다. 게이트웨이 감사 로그에서 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
)"
강제 적용 부분이 끝났습니다. 다음은 정리 섹션입니다.
12. 삭제
# 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
이것으로 정리 부분이 마무리되었습니다. 다음은 결론입니다.
13. 결론
수고하셨습니다 Agent Gateway를 사용하여 도구에 액세스하는 에이전트의 아웃바운드 커뮤니케이션을 배포하고 관리했습니다.
Cosmopup은 Codelab이 최고라고 생각합니다.
다음 단계는 무엇인가요?
- 고급 기능과 튜토리얼은 Gemini Enterprise Agent Platform 문서를 참고하세요.
- 추가 AI 안전 및 보안을 위해 Agent Gateway에서 Model Armor 가드레일 구성
- 시맨틱 거버넌스 정책을 살펴보고 자연어 쿼리에 대한 비즈니스 규칙 및 규정 준수 시행
이 의견 양식을 사용하여 의견, 질문 또는 수정사항을 자유롭게 제공해 주세요.
감사합니다.