Agent Gateway로 에이전트 관리

Agent Gateway를 사용하면 Cloud Run에서 빌드하고 호스팅하는 AI 에이전트의 아웃바운드 트래픽을 제어할 수 있습니다. 보안 웹 프록시에서 실행되는 자체 관리형 Agent Gateway를 통해 Cloud Run 서비스의 이그레스 트래픽을 라우팅하면 중앙 집중식 액세스 정책을 시행하고, 콘텐츠 안전을 위해 페이로드를 검사하고, 에이전트 워크로드 전반에서 모니터링 가능성 원격 분석을 수집할 수 있습니다.

이 문서에서는 Cloud Run에서 Agent Gateway의 중앙 집중식 아키텍처를 구성하는 방법을 설명하고 다음을 수행하는 방법을 다룹니다.

아키텍처

중앙 집중식 자체 관리형 배포에서 Secure Web Proxy는 정책 시행 지점 역할을 하며 Virtual Private Cloud(VPC) 네트워크 내에서 실행됩니다. 앰비언트 네트워킹 사이드카 컨테이너는 Cloud Run 에이전트의 아웃바운드 트래픽을 가로채고 VPC 직접 연결 이그레스를 통해 Secure Web Proxy 인스턴스로 라우팅합니다. 보안 웹 프록시는 IAP(Identity-Aware Proxy) 및 Model Armor와 같은 정책 결정 지점에서 액세스 및 콘텐츠 규칙을 시행합니다.

에이전트 컨테이너와 주변 사이드카 프록시 컨테이너가 있는 Cloud Run 서비스가 VPC 네트워크 내의 Secure Web Proxy로 지원되는 자체 관리형 Agent Gateway로 VPC 직접 연결 이그레스를 통해 트래픽을 라우팅하는 모습을 보여주는 아키텍처 다이어그램
그림 1. Cloud Run 에이전트의 자체 관리형 Agent Gateway 아키텍처

이 아키텍처에서 트래픽을 라우팅하고 제어하려면 다음 구성요소를 구성합니다.

  • VPC 직접 연결 이그레스 및 앰비언트 네트워킹: Cloud Run 서비스가 --vpc-egress=all 및 --ambient-networking를 사용하여 VPC 네트워크에 연결합니다. 이는 기본적으로 리전 범위를 사용하고 모든 아웃바운드 트래픽을 VPC 네트워크로 라우팅합니다.
  • 자체 관리형 Agent Gateway: 자체 관리형 모드의 논리적 Agent Gateway 리소스는 VPC 네트워크의 Secure Web Proxy 인스턴스를 가리킵니다.
  • 이그레스 라우팅 정책: Network Services API EgressRouting 정책은 Cloud Run 서비스에서 Secure Web Proxy 인스턴스로 아웃바운드 트래픽을 전달합니다.

시작하기 전에

  1. Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Install the Google Cloud CLI.

  5. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Install the Google Cloud CLI.

  10. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init

  12. Cloud Run Admin API, Network Services API, 네트워크 보안 API, Service Extensions API, Model Armor API, Certificate Authority Service API, Certificate Manager API, Cloud Resource Manager API, App Hub API, Identity and Access Management API, Identity-Aware Proxy API, Compute Engine API, Traffic Director API, Cloud DNS API, Network Connectivity API, Agent Registry API가 아직 사용 설정되지 않은 경우 사용 설정합니다.

    API 사용 설정에 필요한 역할

    API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할(roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할(roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할 부여 방법 알아보기

    API 사용 설정

  13. 서브넷에 비공개 Google 액세스가 사용 설정된 VPC 네트워크와 서브넷을 만듭니다.
  14. 프로젝트 또는 조직에서 Agent Registry를 설정합니다.
  15. Google Cloud CLI를 설치하고 초기화합니다.
  16. gcloud CLI 구성요소를 업데이트합니다. 
    gcloud components update

필요한 역할

Cloud Run용 Agent Gateway를 구성하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

공유 VPC를 사용하여 프로젝트 간 배포를 구성하는 경우 관리자에게 조직 또는 폴더 수준에서 roles/compute.xpnAdmin을 부여해 달라고 요청하세요.

자체 관리형 Agent Gateway 만들기

Agent Gateway 리소스를 만들기 전에 Agent Gateway로 Secure Web Proxy 배포에 설명된 대로 VPC 네트워크에 Secure Web Proxy 인스턴스를 배포하고 구성합니다.

  1. TLS 검사를 설정하고 TlsInspectionPolicy를 연결하는 게이트웨이 보안 정책을 만듭니다. Secure Web Proxy 보안 정책 규칙이나 URL 목록은 필요하지 않습니다.
  2. allowOpen: false 및 mtlsPolicy.clientValidationMode: ALLOW_INVALID_OR_MISSING_CLIENT_CERT를 사용하여 ServerTlsPolicy 리소스를 만듭니다. clientValidationTrustConfig 설정 안 함
  3. 게이트웨이를 만들 때 addresses, ports, certificateUrls, gatewaySecurityPolicy, serverTlsPolicy가 구성된 명시적 프록시 라우팅 모드에서 Secure Web Proxy 인스턴스를 배포하여 Cloud Run이 mTLS를 통해 에이전트의 워크로드 아이덴티티를 Secure Web Proxy 및 IAP에 전달하도록 합니다.

Secure Web Proxy 인스턴스가 준비되면 Secure Web Proxy 인스턴스를 가리키는 자체 관리형 Agent Gateway 리소스를 만듭니다.

  1. my-agent-gateway.yaml이라는 YAML 구성 파일을 만듭니다.

    name: AGENT_GATEWAY_NAME
registries:
  - "//agentregistry.googleapis.com/projects/PROJECT_ID/locations/REGION"
selfManaged:
  resourceUris:
    - "projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME"

    다음을 바꿉니다.

    • AGENT_GATEWAY_NAME: Agent Gateway 리소스에 할당하려는 이름입니다.
    • PROJECT_ID: Secure Web Proxy 인스턴스를 호스팅하는 프로젝트 ID입니다.
    • REGION: Secure Web Proxy 인스턴스의 리전(예: us-central1)
    • SWP_NAME: Secure Web Proxy 인스턴스의 이름

  2. Agent Gateway 구성을 가져옵니다.

    gcloud beta network-services agent-gateways import AGENT_GATEWAY_NAME \
   --source="my-agent-gateway.yaml" \
   --location=REGION \
   --project=PROJECT_ID

  3. Agent Gateway 리소스를 확인합니다.

    gcloud beta network-services agent-gateways describe AGENT_GATEWAY_NAME \
   --location=REGION \
   --project=PROJECT_ID

    다음 섹션으로 진행하기 전에 출력에 selfManaged 구성과 Secure Web Proxy 인스턴스의 리소스 URI가 표시되는지 확인합니다.

Traffic Director API에 액세스하도록 Cloud Run 앰비언트 네트워킹 구성

VPC 직접 연결 이그레스 및 --vpc-egress=all를 사용하여 Cloud Run 서비스를 구성하면 컨테이너 인스턴스의 모든 아웃바운드 연결이 VPC 네트워크를 통해 라우팅됩니다. 여기에는 trafficdirector.REGION.rep.googleapis.com에 대한 Envoy 사이드카 연결이 포함됩니다.

사이드카가 Traffic Director API를 확인하고 연결할 수 있도록 하려면 환경에서 VPC 서비스 제어를 사용하는지 여부에 따라 VPC 네트워크에서 비공개 Cloud DNS 영역을 구성합니다.

VPC 서비스 제어가 없는 경우

프로젝트에서 VPC 서비스 제어를 사용하지 않는 경우 trafficdirector.REGION.rep.googleapis.com에 대한 요청을 Secure Web Proxy 게이트웨이 IP 주소로 라우팅하는 비공개 Cloud DNS 영역을 만들어 Secure Web Proxy가 트래픽을 통과하도록 합니다.

  1. Secure Web Proxy 게이트웨이의 내부 IP 주소를 가져옵니다.

    SWP_IP=$(gcloud network-services gateways describe SWP_NAME \
 --project="PROJECT_ID" \
 --location="REGION" \
 --format="value(addresses[0])")

    다음을 바꿉니다.

    • SWP_NAME: Secure Web Proxy 인스턴스의 이름
    • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
    • REGION: 배포의 리전입니다.

  2. Traffic Director API의 비공개 Cloud DNS 관리형 영역을 만듭니다.

    gcloud dns managed-zones create td-swp-zone \
 --project="PROJECT_ID" \
 --dns-name="trafficdirector.REGION.rep.googleapis.com." \
 --description="Private DNS zone routing control plane traffic to SWP" \
 --visibility="private" \
 --networks="VPC_NETWORK_NAME"

    VPC_NETWORK_NAME를 VPC 네트워크 이름으로 바꿉니다.

  3. Traffic Director API 리전 도메인을 Secure Web Proxy IP 주소로 가리키는 A 레코드를 추가합니다.

    gcloud dns record-sets create "trafficdirector.REGION.rep.googleapis.com." \
 --project="PROJECT_ID" \
 --zone="td-swp-zone" \
 --type="A" \
 --ttl=300 \
 --rrdatas="${SWP_IP}"

  4. DNS 레코드 세트가 비공개 영역에서 활성 상태인지 확인합니다.

    gcloud dns record-sets list \
 --project="PROJECT_ID" \
 --zone="td-swp-zone"

    trafficdirector.REGION.rep.googleapis.com.의 A 레코드가 Secure Web Proxy IP 주소로 확인되는지 확인합니다.

VPC 서비스 제어 사용

VPC 서비스 제어 환경의 경우 VPC 서브넷 내에서 리전 Traffic Director API를 타겟팅하는 Private Service Connect 리전 엔드포인트를 프로비저닝하고 비공개 Cloud DNS 영역을 사용하여 도메인을 매핑합니다.

  1. 리전 Traffic Director API를 타겟팅하는 Private Service Connect 리전 엔드포인트를 만듭니다.

    gcloud network-connectivity regional-endpoints create td-rep-endpoint \
 --project="PROJECT_ID" \
 --region="REGION" \
 --network="projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME" \
 --subnetwork="projects/PROJECT_ID/regions/REGION/subnetworks/VPC_SUBNET_NAME" \
 --target-google-api="trafficdirector.REGION.rep.googleapis.com"

    다음을 바꿉니다.

    • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
    • REGION: 배포의 리전입니다.
    • VPC_NETWORK_NAME: VPC 네트워크의 이름입니다.
    • VPC_SUBNET_NAME: VPC 서브넷의 이름입니다.

  2. 리전 엔드포인트의 내부 IP 주소를 가져옵니다.

    TD_ENDPOINT_IP=$(gcloud network-connectivity regional-endpoints describe td-rep-endpoint \
 --project="PROJECT_ID" \
 --region="REGION" \
 --format="value(address)")

  3. Traffic Director API의 비공개 Cloud DNS 관리형 영역을 만듭니다.

    gcloud dns managed-zones create td-psc-zone \
 --project="PROJECT_ID" \
 --dns-name="trafficdirector.REGION.rep.googleapis.com." \
 --description="Private DNS zone for regional endpoint" \
 --visibility="private" \
 --networks="VPC_NETWORK_NAME"

  4. Traffic Director API 리전 도메인을 리전 엔드포인트 IP 주소로 변환하는 A 레코드를 추가합니다.

    gcloud dns record-sets create "trafficdirector.REGION.rep.googleapis.com." \
 --project="PROJECT_ID" \
 --zone="td-psc-zone" \
 --type="A" \
 --ttl=300 \
 --rrdatas="${TD_ENDPOINT_IP}"

  5. 리전 엔드포인트 및 DNS 레코드 세트를 확인합니다.

    gcloud dns record-sets list \
 --project="PROJECT_ID" \
 --zone="td-psc-zone"

    trafficdirector.REGION.rep.googleapis.com.의 A 레코드가 리전 엔드포인트 IP 주소를 가리키는지 확인합니다.

앰비언트 네트워킹 및 VPC 직접 연결 이그레스를 사용하여 Cloud Run 서비스 배포 또는 업데이트

Cloud Run 에이전트를 VPC 네트워크의 보안 웹 프록시 인스턴스에 연결하려면 직접 VPC 이그레스와 리전 앰비언트 네트워킹을 모두 사용 설정하고 에이전트 ID로 서비스를 구성합니다. --functional-type=agent 및 --identity-type=agent-identity를 사용하여 배포하면 Cloud Run은 roles/trafficdirector.client 및 roles/cloudtrace.agent 권한이 포함된 roles/run.agentDefaultAccess를 부여합니다.

  1. 새 Cloud Run 에이전트 서비스를 배포하거나 기존 서비스를 업데이트하여 리전 앰비언트 네트워킹, 모든 아웃바운드 트래픽에 대한 VPC 직접 연결 이그레스, 에이전트 ID를 사용 설정합니다.

    새 서비스

    gcloud beta run deploy SERVICE_NAME \
 --image=IMAGE_URL \
 --network=VPC_NETWORK_NAME \
 --subnet=VPC_SUBNET_NAME \
 --vpc-egress=all \
 --functional-type=agent \
 --identity-type=agent-identity \
 --ambient-networking \
 --set-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
 --region=REGION \
 --project=PROJECT_ID

    기존 서비스

    gcloud beta run services update SERVICE_NAME \
 --network=VPC_NETWORK_NAME \
 --subnet=VPC_SUBNET_NAME \
 --vpc-egress=all \
 --functional-type=agent \
 --identity-type=agent-identity \
 --ambient-networking \
 --update-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
 --region=REGION \
 --project=PROJECT_ID

    다음을 바꿉니다.

    • SERVICE_NAME: Cloud Run 에이전트 서비스의 이름입니다.
    • IMAGE_URL: 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/hello:latest). Artifact Registry를 사용하는 경우 저장소 REPO_NAME이 이미 생성되어 있어야 합니다. URL은 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG 형식을 따릅니다.
    • VPC_NETWORK_NAME: Secure Web Proxy 인스턴스를 호스팅하는 VPC 네트워크의 이름입니다. VPC 네트워크 및 서브넷 만들기에 대한 자세한 내용은 VPC 네트워크 만들기 및 관리를 참조하세요.
    • VPC_SUBNET_NAME: Secure Web Proxy 인스턴스에 연결할 수 있는 VPC 서브넷의 이름입니다.
    • REGION: 서비스의 리전
    • PROJECT_ID: Google Cloud 프로젝트 ID입니다.

  2. Cloud Run 서비스에서 앰비언트 네트워킹, VPC 직접 연결 이그레스, 에이전트 ID를 사용하는지 확인합니다.

    gcloud beta run services describe SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID

    출력에 VPC 직접 연결 이그레스 서브넷, all-traffic 이그레스, 리전 앰비언트 네트워킹, 할당된 에이전트 ID 주 구성원이 표시되는지 확인합니다.

Agent Gateway를 신뢰하도록 Cloud Run 에이전트 구성

Secure Web Proxy가 HTTPS 페이로드를 검사하고 정책을 시행하려면 에이전트의 아웃바운드 TLS 세션을 종료해야 합니다. Cloud Run 에이전트 컨테이너는 CA 서비스의 Secure Web Proxy TLS 검사 정책 또는 비공개 엔터프라이즈 PKI와 연결된 루트 또는 하위 인증 기관(CA) 인증서를 신뢰해야 합니다.

  1. Secure Web Proxy 인스턴스의 CA 서비스 풀에서 PEM으로 인코딩된 CA 인증서를 내보냅니다.

    gcloud privateca pools get-ca-certs CA_POOL_NAME \
   --location=REGION \
   --project=PROJECT_ID \
   --output-file=agent-gateway-root.crt

    다음을 바꿉니다.

    • CA_POOL_NAME: Secure Web Proxy TLS 검사 정책과 연결된 CA 풀의 이름입니다.
    • REGION: CA 풀의 리전입니다.
    • PROJECT_ID: Google Cloud 프로젝트 ID입니다.

  2. 환경 변수에서 인증서 콘텐츠를 전달하도록 Cloud Run 서비스를 업데이트합니다.

    gcloud beta run services update SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID \
   --update-env-vars="AGENT_GATEWAY_ROOT_CERT=$(cat agent-gateway-root.crt)"

    다음을 바꿉니다.

    • SERVICE_NAME: Cloud Run 에이전트 서비스의 이름입니다.
    • REGION: 서비스의 리전
    • PROJECT_ID: Google Cloud 프로젝트 ID입니다.

    예를 들어 다음 Debian 또는 Ubuntu 컨테이너 진입점 스크립트인 entrypoint.sh는 애플리케이션을 시작하기 전에 AGENT_GATEWAY_ROOT_CERT를 시스템 트러스트 저장소에 설치하고 Python 및 gRPC 클라이언트의 CA 번들 경로를 내보냅니다.

    #!/usr/bin/env bash
set -e
if [ -n "${AGENT_GATEWAY_ROOT_CERT}" ]; then
 printf '%s\n' "${AGENT_GATEWAY_ROOT_CERT}" > /usr/local/share/ca-certificates/agent-gateway.crt
 update-ca-certificates
 export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
 export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
 export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/etc/ssl/certs/ca-certificates.crt
fi
exec "$@"

  3. 서비스가 AGENT_GATEWAY_ROOT_CERT 환경 변수를 설정하는지 확인합니다.

    gcloud beta run services describe SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID \
   --format="yaml(spec.template.spec.containers[0].env)"

이그레스 트래픽을 Agent Gateway로 라우팅

Cloud Run 서비스와 Agent Gateway를 구성한 후 Cloud Run 서비스에서 Secure Web Proxy 게이트웨이로 아웃바운드 트래픽을 전달하는 Network Services API EgressRouting 정책을 만듭니다.

  1. EgressRouting 리소스를 만듭니다.

    gcloud alpha network-services egress-routings create my-run-egress-routing \
   --location=REGION \
   --project=PROJECT_ID \
   --gateway="//networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME" \
   --sources="workloadUri=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME"

    다음을 바꿉니다.

    • REGION: Cloud Run 서비스 및 게이트웨이의 리전입니다.
    • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
    • SWP_NAME: AgentGateway 리소스가 아닌 기본 Secure Web Proxy Gateway 리소스의 이름입니다.
    • SERVICE_NAME: Cloud Run 에이전트 서비스의 이름입니다. 단일 정책을 사용하여 게이트웨이를 통해 프로젝트의 모든 Cloud Run 서비스를 라우팅하려면 workloadUri를 //run.googleapis.com/projects/PROJECT_ID 또는 //run.googleapis.com/projects/PROJECT_NUMBER로 설정합니다.

    EgressRouting가 적용되면 Cloud Run 서비스의 모든 아웃바운드 트래픽이 Secure Web Proxy를 통해 라우팅됩니다. 다음 섹션에서 정책을 구성하여 아웃바운드 요청을 허용하고 관리합니다.

  2. EgressRouting 리소스가 활성 상태인지 확인합니다.

    gcloud alpha network-services egress-routings describe my-run-egress-routing \
   --location=REGION \
   --project=PROJECT_ID

    sources에 Cloud Run 워크로드 URI가 나열되고 gateway가 Secure Web Proxy 게이트웨이 리소스를 참조하는지 확인합니다.

Agent Gateway에서 정책 구성

Agent Gateway를 통해 이그레스 트래픽을 라우팅한 후 승인 정책과 Service Extensions 확장 프로그램 바인딩을 Agent Gateway 리소스에 연결하여 에이전트의 아웃바운드 요청을 관리합니다.

  • 기준 트래픽 및 MCP 도구 필터링: ALLOW 승인 정책을 사용하여 모델 엔드포인트와 승인된 모델 컨텍스트 프로토콜(MCP) 메서드 및 도구를 허용합니다.
  • ID 기반 액세스 제어: IAP를 ExtensionBinding 리소스와 바인딩하고 IAM 통합 액세스 정책을 구성하여 특정 MCP 서버, 도구 또는 엔드포인트를 호출할 수 있는 에이전트를 제어합니다.
  • 콘텐츠 보안: Model Armor를 ExtensionBinding 리소스와 바인딩하여 프롬프트 인젝션, 민감한 데이터 유출 또는 정책 위반에 대해 프롬프트와 대답을 검사하고 정제합니다.

기본 Secure Web Proxy Gateway 리소스에 연결된 승인 정책 또는 게이트웨이 보안 정책 규칙은 무시됩니다. ExtensionBinding 리소스를 만들거나 업데이트한 후 변경사항이 게이트웨이에 전파되는 데 최대 5분이 걸릴 수 있습니다. 네트워크 규칙, TLS 검사, 확장 프로그램 바인딩, HTTP 규칙의 규칙 평가 시퀀스는 승인 규칙 평가 순서를 참조하세요.

기준 이그레스 및 MCP 트래픽 허용

Secure Web Proxy는 Agent Gateway 리소스의 ALLOW AuthzPolicy에서 허용할 때까지 기본적으로 403 Forbidden 오류가 있는 모든 아웃바운드 트래픽을 거부합니다.

Cloud Run 서비스는 --vpc-egress=all를 사용하므로 MCP 도구 호출 및 LLM 요청을 포함한 모든 아웃바운드 컨테이너 트래픽이 게이트웨이를 통해 라우팅됩니다. 두 트래픽 유형 모두에 대해 ALLOW 승인 정책을 Agent Gateway 리소스에 연결합니다.

IAP 이그레스 정책 구성

Agent Gateway는 IAP를 정책 결정 엔진으로 사용하여 IAM 통합 액세스 정책을 평가합니다. 에이전트 ID 정책을 시행하려면 IAM 통합 액세스 정책에서 액세스 규칙을 정의하고 IAP를 게이트웨이에 바인딩합니다.

  1. Cloud Run 서비스의 에이전트 ID 주 구성원인 principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME를 사용하여 IAM 통합 액세스 정책을 만들고 IAM 액세스 정책 만들기 및 프로젝트에 통합 액세스 정책 바인딩에 따라 정책을 프로젝트 또는 게이트웨이에 바인딩합니다.
  2. IAP를 Agent Gateway에 바인딩의 안내에 따라 ExtensionBinding를 사용하여 IAP(iap.googleapis.com)를 Agent Gateway에 바인딩합니다.

--vpc-egress=all는 게이트웨이를 통해 REGION-aiplatform.googleapis.com와 같은 모델 호출을 전송하므로 모델 호출이 IAP 평가를 우회하도록 IAP ExtensionBinding의 matchConditions 범위를 prefix: "urn:mcp"로 지정합니다. 에이전트 간 트래픽도 제어하려면 prefix: "urn:agent"를 추가합니다. 확장 프로그램 바인딩이 다른 호스트와 일치하는 경우 IAM 통합 액세스 정책의 각 호스트에 허용 규칙을 추가합니다(예: destination.unregistered.host == 'REGION-aiplatform.googleapis.com'). 예시는 에이전트-미등록 엔드포인트 정책 만들기를 참조하세요.

Model Armor 정책 구성

Agent Gateway를 통과하는 프롬프트와 대답을 검사하고 정제하려면 Model Armor 템플릿을 만들고 게이트웨이에 바인딩합니다.

  1. 게이트웨이에서 Model Armor 구성의 안내에 따라 리전 Model Armor 요청 및 응답 템플릿을 만들고 서비스 확장 프로그램 서비스 에이전트에 필요한 역할을 부여합니다.
  2. 프롬프트 및 응답 정제를 위해 Model Armor 바인딩의 안내에 따라 ExtensionBinding를 사용하여 템플릿을 Agent Gateway에 연결합니다.

공유 VPC를 사용하여 중앙 집중식 프로젝트 간 배포 구성

여러 프로젝트가 있는 조직에서는 공유 VPC를 사용하여 전용 네트워킹 호스트 프로젝트에서 Agent Gateway, Secure Web Proxy 인스턴스, Agent Registry를 호스팅하면서 하나 이상의 서비스 프로젝트에 Cloud Run 에이전트를 배포할 수 있습니다.

  • 프로젝트 A, 에이전트 서비스 프로젝트: Cloud Run 에이전트 서비스와 로컬 EgressRouting 정책을 호스팅합니다.
  • 프로젝트 B, 게이트웨이 및 네트워킹 호스트 프로젝트: 공유 VPC 호스트 프로젝트 역할을 하며 Agent Gateway, Secure Web Proxy 인스턴스, Agent Registry, ExtensionBinding 리소스, IAM 정책 바인딩을 호스팅해야 합니다.
Cloud Run 서비스 및 이그레스 라우팅 정책을 호스팅하는 프로젝트 A가 공유 VPC 네트워크를 통해 Agent Gateway, Secure Web Proxy, Agent Registry를 호스팅하는 프로젝트 B에 연결된 모습을 보여주는 프로젝트 간 아키텍처 다이어그램
그림 2. 공유 VPC를 사용한 프로젝트 간 Agent Gateway 배포

이 단계를 시작하기 전에 에이전트가 Vertex AI를 호출하는 경우 aiplatform.googleapis.com와 함께 프로젝트 A에서 run.googleapis.com, compute.googleapis.com, networkservices.googleapis.com, trafficdirector.googleapis.com를 사용 설정합니다. 프로젝트 B에서 자체 관리형 Agent Gateway 만들기에 설명된 대로 공유 VPC 네트워크에 Secure Web Proxy 인스턴스와 Agent Gateway 리소스를 배포하고, 프로젝트 A의 주변 사이드카가 Traffic Director API에 도달할 수 있도록 Traffic Director API에 액세스하도록 Cloud Run 앰비언트 네트워킹 구성에 설명된 대로 DNS 또는 Private Service Connect 라우팅을 구성합니다.

프로젝트 간 배포를 구성하려면 다음 단계를 완료하세요.

  1. 프로젝트 B를 공유 VPC 호스트 프로젝트로 구성하고, 프로젝트 A를 서비스 프로젝트로 연결하고, Secure Web Proxy 인스턴스를 호스팅하는 서브넷을 공유합니다. 공유 VPC를 사용 설정하고 서비스 프로젝트를 연결하려면 조직 또는 폴더 수준에서 roles/compute.xpnAdmin이 필요합니다. 자세한 내용은 직접 VPC 이그레스를 사용하여 공유 VPC 네트워크로 트래픽 전송 및 공유 VPC 프로비저닝을 참조하세요.

  2. 프로젝트 B에서 공유 서브넷에 대한 roles/compute.networkUser을 프로젝트 A의 Cloud Run 서비스 에이전트에 부여합니다.

    gcloud compute networks subnets add-iam-policy-binding SHARED_SUBNET_NAME \
   --project=PROJECT_B_ID \
   --region=REGION \
   --member="serviceAccount:service-PROJECT_A_NUMBER@serverless-robot-prod.iam.gserviceaccount.com" \
   --role="roles/compute.networkUser"

    다음을 바꿉니다.

    • SHARED_SUBNET_NAME: 프로젝트 B의 공유 서브넷 이름
    • PROJECT_B_ID: 게이트웨이 및 공유 VPC 호스트 프로젝트인 프로젝트 B의 프로젝트 ID입니다.
    • REGION: 공유 서브넷의 리전입니다.
    • PROJECT_A_NUMBER: 에이전트 서비스 프로젝트인 프로젝트 A의 프로젝트 번호입니다.

  3. 프로젝트 B의 공유 서브넷을 가리키는 프로젝트 A에 Cloud Run 에이전트 서비스를 배포합니다.

    gcloud beta run deploy SERVICE_NAME \
   --project=PROJECT_A_ID \
   --image=IMAGE_URL \
   --subnet=projects/PROJECT_B_ID/regions/REGION/subnetworks/SHARED_SUBNET_NAME \
   --vpc-egress=all \
   --functional-type=agent \
   --identity-type=agent-identity \
   --ambient-networking \
   --set-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
   --region=REGION

    다음을 바꿉니다.

    • SERVICE_NAME: 프로젝트 A에 있는 Cloud Run 에이전트 서비스의 이름입니다.
    • PROJECT_A_ID: 에이전트 서비스 프로젝트인 프로젝트 A의 프로젝트 ID입니다.
    • IMAGE_URL: 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/hello:latest). Artifact Registry를 사용하는 경우 저장소 REPO_NAME이 이미 생성되어 있어야 합니다. URL은 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG 형식을 따릅니다.

    서비스를 배포한 후 Agent Gateway를 신뢰하도록 Cloud Run 에이전트 구성의 단계에 따라 프로젝트 B의 Secure Web Proxy 인스턴스의 루트 CA 인증서를 신뢰하도록 프로젝트 A의 에이전트를 구성합니다.

  4. 프로젝트 B의 Secure Web Proxy 게이트웨이를 참조하는 EgressRouting 정책을 프로젝트 A에 만듭니다. 프로젝트 A에 roles/networkservices.admin가 있어야 합니다.

    gcloud alpha network-services egress-routings create my-central-egress-routing \
   --location=REGION \
   --project=PROJECT_A_ID \
   --gateway="//networkservices.googleapis.com/projects/PROJECT_B_ID/locations/REGION/gateways/CENTRAL_SWP_NAME" \
   --sources="workloadUri=//run.googleapis.com/projects/PROJECT_A_ID/locations/REGION/services/SERVICE_NAME"

    CENTRAL_SWP_NAME를 프로젝트 B의 Secure Web Proxy 게이트웨이 이름으로 바꿉니다. 프로젝트 A의 모든 Cloud Run 서비스를 프로젝트 B의 게이트웨이를 통해 라우팅하려면 workloadUri를 //run.googleapis.com/projects/PROJECT_A_ID 또는 //run.googleapis.com/projects/PROJECT_A_NUMBER로 설정합니다.

  5. 프로젝트 간 EgressRouting 리소스가 프로젝트 A에서 활성 상태인지 확인합니다.

    gcloud alpha network-services egress-routings describe my-central-egress-routing \
   --location=REGION \
   --project=PROJECT_A_ID

  6. Agent Gateway에서 정책 구성에 설명된 대로 프로젝트 B의 Agent Gateway 리소스에서 중앙 집중식 기준, IAP, Model Armor 정책을 구성합니다.

    • 기준 이그레스 및 MCP 트래픽 허용에 따라 프로젝트 B의 Agent Gateway 리소스에서 기준 MCP 및 모델 트래픽을 허용합니다.
    • 프로젝트 A의 에이전트가 프로젝트 B에 등록된 MCP 서버를 호출하도록 승인하려면 프로젝트 B에서 principals 목록이 프로젝트 A의 프로젝트 번호(principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_A_NUMBER/locations/REGION/services/SERVICE_NAME)를 참조하는 IAM 통합 액세스 정책을 만들고, 이 정책을 프로젝트 B 또는 해당 Agent Gateway 리소스에 바인딩하고, 프로젝트 B에서 IAP ExtensionBinding를 연결합니다.
    • 프로젝트 B에 중앙 집중식 Model Armor 가드레일을 적용하려면 리전 Model Armor 템플릿을 만들고, 프로젝트 B의 서비스 확장 프로그램 서비스 에이전트에 필요한 역할을 부여하고, Model Armor ExtensionBinding를 프로젝트 B의 Agent Gateway 리소스에 연결합니다.

로그 및 trace 보기

Agent Gateway를 통해 라우팅되는 아웃바운드 에이전트 상호작용은 로그와 분산 trace를 생성하므로 정책 결정을 모니터링하고 에이전트 동작을 디버깅할 수 있습니다.

아웃바운드 요청이 실패하거나 게이트웨이를 우회하는 경우 Agent Gateway 문제 해결을 참조하세요.

지원되는 리전

다음 리전의 Cloud Run에서 Agent Gateway를 사용할 수 있습니다.

  • europe-west1
  • us-central1

제한사항

앰비언트 네트워킹 제한사항과 Secure Web Proxy를 Agent Gateway로 배포의 Secure Web Proxy 고려사항 외에도 Cloud Run에서 Agent Gateway를 사용할 때는 다음 제한사항이 적용됩니다.

  • TLS 검사 Secure Web Proxy 인스턴스를 통해 *.mtls.googleapis.com 및 *.mtls.run.app 엔드포인트로 라우팅되는 아웃바운드 에이전트 요청은 Secure Web Proxy가 클라이언트 인증서를 전달하지 않고 TLS 세션을 종료하고 다시 시작하기 때문에 503 오류와 함께 실패합니다.
  • 각 리전별 자체 관리형 Agent Gateway는 registries 목록에서 최대 하나의 리전별 Agent Registry를 지원합니다.
  • 기본적으로 각 프로젝트는 리전별로 최대 10개의 리전 AgentGateway 리소스와 10개의 리전 EgressRouting 리소스를 지원합니다. 새 프로젝트는 리전당 2개로 제한될 수 있습니다. 할당량 증가를 요청하려면 계정팀에 문의하세요.
  • CA Service 풀 또는 비공개 엔터프라이즈 PKI에서 루트 또는 하위 인증서를 내보내고 이를 신뢰하도록 에이전트 컨테이너를 구성해야 합니다.

다음 단계