에이전트 게이트웨이를 통해 에이전트 런타임 트래픽 라우팅

비공개 프리뷰 - 에이전트 게이트웨이

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제품 또는 서비스 약관'이 적용됩니다. 이 기능은 AI 에이전트를 관리하고 보호하는 기능을 제공하므로 '에이전트 AI 서비스' 서비스별 약관이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참고하세요.

에이전트 런타임과 함께 에이전트 게이트웨이를 사용할 수 있는 액세스 권한을 요청하려면 액세스 요청 페이지를 참고하세요.

이 페이지에서는 에이전트 게이트웨이를 통해 에이전트 런타임 트래픽을 라우팅하는 방법을 설명합니다. 에이전트 게이트웨이는 Gemini Enterprise 에이전트 플랫폼 생태계의 중앙 네트워킹 및 보안 구성요소입니다. 사용자와 에이전트 간, 에이전트와 도구 간 또는 에이전트 간에 발생하는 모든 에이전트 상호작용에 안전하고 관리되는 연결을 제공합니다.

시작하기 전에

• 에이전트 런타임에 에이전트를 배포하는 방법을 숙지해야 합니다.

• 에이전트 게이트웨이에 대해 알아봅니다. 에이전트-투-애니웨어 (이그레스) 모드에서 에이전트 게이트웨이를 사용하여 도구, 모델, API, 기타 에이전트로의 아웃바운드 트래픽을 포함한 모든 아웃바운드 통신을 보호하고 관리할 수 있습니다. 클라이언트-에이전트(수신) 모드에서 게이트웨이를 사용하여 에이전트에 액세스할 수 있는 클라이언트를 제어합니다. 게이트웨이를 사용하면 이러한 상호작용에 적용해야 하는 IAP 정책과 Model Armor 템플릿을 선택할 수 있습니다.

• 이 워크플로를 사용해 보려면 전용 테스트 프로젝트를 만드세요. 다른 중요한 워크로드에도 사용되는 프로젝트는 사용하지 마세요.

제한사항

• 특정 프로젝트 및 리전의 경우 에이전트 게이트웨이의 Agent-to-Anywhere (이그레스) 인스턴스 하나와 Client-to-Agent (인그레스) 인스턴스 하나만 있을 수 있습니다. 에이전트 게이트웨이를 사용하도록 구성된 동일한 프로젝트 및 리전 내의 모든 에이전트 런타임 에이전트는 이러한 특정 게이트웨이 인스턴스를 사용해야 합니다.
• Security Command Center Agent Engine Threat Detection 서비스는 에이전트에 대해 에이전트 게이트웨이가 사용 설정된 경우 사용할 수 없습니다.
• 런타임 에이전트를 에이전트 게이트웨이 리소스에서 바인딩 해제할 수 없습니다. 따라서 전용 테스트 프로젝트를 사용해야 합니다.

에이전트 게이트웨이를 통해 에이전트 런타임 트래픽 라우팅

에이전트 게이트웨이를 통해 에이전트 런타임 트래픽을 라우팅하려면 다음 단계를 수행하세요.

1. 에이전트 게이트웨이 리소스를 만들고 필요한 승인 정책을 연결합니다. 에이전트-어디로든 (이그레스) 모드 또는 클라이언트-에이전트 (인그레스) 모드에서 게이트웨이를 만들 수 있습니다. 에이전트와 게이트웨이는 동일한 프로젝트와 리전에서 생성해야 합니다. 자세한 내용은 에이전트 게이트웨이 설정을 참고하세요.

   게이트웨이가 배포 요구사항을 충족하도록 구성되어 있는지 확인합니다. 예를 들어 에이전트에 LLM 액세스가 필요한 경우 잠재적인 에이전트 런타임 배포 실패를 방지하기 위해 이 액세스를 허용하도록 게이트웨이를 구성합니다.

2. 에이전트를 배포하는 동안 게이트웨이 리소스를 지정합니다. 예를 들어 에이전트 런타임에 에이전트를 배포하려면 client.agent_engines.create를 사용하여 local_agent 객체를 선택적 구성과 함께 전달합니다.

   또한 이 예에 표시된 대로 identity_type 매개변수를 사용하여 런타임 인스턴스에 에이전트 ID가 할당되었는지 확인해야 합니다.

   remote_agent = client.agent_engines.create(
     agent=local_agent,
     config={
         "agent_gateway_config": {
           "agent_to_anywhere_config": {"agent_gateway": AGENT_GATEWAY_TO_ANYWHERE_NAME},
           # "client_to_agent_config": {"agent_gateway": AGENT_GATEWAY_CLIENT_TO_AGENT_NAME}
         },
         "identity_type": types.IdentityType.AGENT_IDENTITY,
         # Other optional configuration ...
         # "requirements": requirements,
         # "gcs_dir_name": gcs_dir_name,
         # https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity#opt-out-caa
         "env_vars": {
           "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
         }
     },
   )

   AGENT_GATEWAY_TO_ANYWHERE_NAME을 에이전트-투-애니웨어(egress) 모드에서 만든 에이전트 게이트웨이의 전체 경로로 바꿉니다. 예를 들면 projects/PROJECT/locations/REGION/agentGateways/AGENT_GATEWAY_ID입니다.

   클라이언트-에이전트 (인그레스) 모드에서 게이트웨이를 만든 경우 대신 client_to_agent_config 필드를 사용하고 AGENT_GATEWAY_CLIENT_TO_AGENT_NAME을 인그레스를 위해 만든 에이전트 게이트웨이의 전체 경로로 바꿉니다.

3. 에이전트 및 게이트웨이와 동일한 프로젝트 및 리전의 에이전트 레지스트리 인스턴스에 에이전트를 등록합니다. 자세한 내용은 에이전트 등록을 참고하세요.

승인된 에이전트 게이트웨이로 에이전트 런타임 제한

에이전트를 배포하는 동안 사용할 수 있는 적격한 에이전트 게이트웨이 리소스 집합을 정의하는 맞춤 조직 정책 제약 조건을 만들 수 있습니다.

참고: 에이전트 게이트웨이에서는 VPC 서비스 제어가 지원되지 않습니다. 하지만 프로젝트에 VPC 서비스 제어가 적용되는 경우 에이전트가 승인된 출구 경로만 사용하도록 하여 무단 게이트웨이를 통한 데이터 무단 반출을 방지하려면 이러한 조직 정책이 필요합니다.

커스텀 조직 정책 제약조건 만들기

이 예시에서는 사전 승인된 게이트웨이 목록으로 오가는 트래픽만 허용하는 맞춤 제약 조건을 만듭니다.

에이전트에서 모든 위치로

1. 에이전트-임의 위치 모드 (이그레스)의 맞춤 제약 조건을 정의하려면 constraint-agent-gateway-egress.yaml라는 파일을 만듭니다.

   다음 예에서 condition 필드는 에이전트 게이트웨이 리소스가 지정된 경우(필드가 있고 비어 있지 않음) 지정된 게이트웨이가 사전 승인된 목록에 있는 경우에만 작업이 허용됨을 지정합니다.

   name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedEgressAgentGatewaysForAgentEngine
   resource_types:
   - aiplatform.googleapis.com/ReasoningEngine
   condition: >-
   has(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway) &&
   resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway != '' &&
   (resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway in [
     'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
     'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
   ])
   method_types:
   - CREATE
   - UPDATE
   action_type: ALLOW
   display_name: Restrict Reasoning Engine Egress to Approved Agent Gateways
   description: Reasoning Engines can only be bound to a pre-approved list of
   Agent Gateway instances. Binding to any other gateway is denied.
   

   다음을 바꿉니다.

   • ORGANIZATION_ID: 조직 ID입니다.
   • AGENT_PROJECT_ID: 프로젝트 ID입니다.
   • REGION: 게이트웨이가 생성된 리전입니다.
   • AGENT_GATEWAY_ID: 게이트웨이 ID입니다.

2. 커스텀 제약조건을 적용합니다.

   gcloud alpha org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH
   

   EGRESS_CONSTRAINT_PATH을 이전 단계에서 만든 맞춤 제약 조건 파일의 전체 경로로 바꿉니다.

3. 제약 조건을 적용하는 조직 정책을 만듭니다. 조직 정책을 정의하려면 policy-agent-gateway-egress.yaml이라는 정책 YAML 파일을 만듭니다. 이 예시에서는 프로젝트 수준에서 이 제약조건을 적용하지만 조직 또는 폴더 수준에서 이를 설정할 수도 있습니다.

   name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedEgressAgentGatewaysForAgentEngine
   spec:
     rules:
     - enforce: true
   

   AGENT_PROJECT_ID를 프로젝트 ID로 바꿉니다.

4. 조직 정책을 적용합니다.

   gcloud alpha org-policies set-policy EGRESS_POLICY_PATH
   

   EGRESS_POLICY_PATH을 이전 단계에서 만든 조직 정책 YAML 파일의 전체 경로로 바꿉니다. 정책이 적용되는 데 최대 15분이 소요됩니다.

클라이언트에서 에이전트로

1. 클라이언트-에이전트 모드 (인그레스)의 맞춤 제약 조건을 정의하려면 constraint-agent-gateway-ingress.yaml라는 파일을 만듭니다.

   다음 예에서 condition 필드는 에이전트 게이트웨이 리소스가 지정된 경우(필드가 있고 비어 있지 않음) 지정된 게이트웨이가 사전 승인된 목록에 있는 경우에만 작업이 허용됨을 지정합니다.

   name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedIngressAgentGatewaysForAgentEngine
   resource_types:
   - aiplatform.googleapis.com/ReasoningEngine
   condition: >-
   has(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway) &&
   resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway != '' &&
   (resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway in [
     'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
     'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
   ])
   method_types:
   - CREATE
   - UPDATE
   action_type: ALLOW
   display_name: Restrict Reasoning Engine Ingress to Approved Agent Gateways
   description: Reasoning Engines can only be bound to a pre-approved list of
   Agent Gateway instances. Binding to any other gateway is denied.
   

   다음을 바꿉니다.

   • ORGANIZATION_ID: 조직 ID입니다.
   • AGENT_PROJECT_ID: 프로젝트 ID입니다.
   • REGION: 게이트웨이가 생성된 리전입니다.
   • AGENT_GATEWAY_ID: 게이트웨이 ID입니다.

2. 커스텀 제약조건을 적용합니다.

   gcloud alpha org-policies set-custom-constraint INGRESS_CONSTRAINT_PATH
   

   INGRESS_CONSTRAINT_PATH을 이전 단계에서 만든 맞춤 제약 조건 파일의 전체 경로로 바꿉니다.

3. 제약 조건을 적용하는 조직 정책을 만듭니다. 조직 정책을 정의하려면 policy-agent-gateway-ingress.yaml이라는 정책 YAML 파일을 만듭니다. 이 예시에서는 프로젝트 수준에서 이 제약조건을 적용하지만 조직 또는 폴더 수준에서 이를 설정할 수도 있습니다.

   name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedIngressAgentGatewaysForAgentEngine
   spec:
     rules:
     - enforce: true
   

   AGENT_PROJECT_ID를 프로젝트 ID로 바꿉니다.

4. 조직 정책을 적용합니다.

   gcloud alpha org-policies set-policy INGRESS_POLICY_PATH
   

   INGRESS_POLICY_PATH을 이전 단계에서 만든 조직 정책 YAML 파일의 전체 경로로 바꿉니다. 정책이 적용되는 데 최대 15분이 소요됩니다.

커스텀 조직 정책 제약 조건을 사용하는 방법에 대한 자세한 내용은 커스텀 제약 조건 만들기를 참고하세요.

다음 단계

Codelab

Codelab: Govern agentic workloads with Agent Platform

Gemini Enterprise Agent Platform에서 Agent Gateway를 사용하여 에이전트 워크로드를 관리하는 방법을 알아봅니다.

가이드

에이전트 게이트웨이 승인 위임

에이전트 게이트웨이의 승인을 IAP, Model Armor 또는 자체 맞춤 승인 서비스에 위임하는 방법을 알아봅니다.

가이드

Monitor Agent Gateway

에이전트 게이트웨이를 모니터링하는 방법을 알아봅니다.