Agent Gateway를 통해 Gemini Enterprise 트래픽 라우팅

이 페이지에서는 Agent Gateway를 통해 Gemini Enterprise 트래픽을 라우팅하는 방법을 설명합니다. Agent Gateway는 Gemini Enterprise Agent Platform 생태계의 핵심 네트워킹 및 보안 구성요소입니다. 사용자와 에이전트 간, 에이전트와 도구 간, 에이전트 간에 발생하는 모든 에이전트형 상호작용에 대해 안전하고 제어되는 연결을 제공합니다.

시작하기 전에

• Gemini Enterprise 개념을 숙지해야 합니다.
• Agent Gateway에 대해 알아보기 Agent Gateway는 Agent-to-Anywhere (이그레스) 모드에서 Gemini Enterprise만 지원합니다. 인그레스 트래픽은 지원되지 않습니다.
• Gemini Enterprise 앱 (엔진이라고도 함)을 배포합니다. 이 페이지의 절차에서는 이미 앱이 배포되었다고 가정합니다. 자세한 내용은 앱 만들기를 참고하세요.

위치 및 에이전트 레지스트리 매핑 계획

Agent Gateway를 배포하기 전에 게이트웨이를 배포할 리전과 리소스를 등록할 Agent Registry를 선택합니다. 다음 요구사항을 참고하세요.

• 위치 매핑: 적절한 라우팅을 위해 Gemini Enterprise 앱의 위치에 해당하는 특정 리전에 Agent Gateway를 배포합니다.

• 레지스트리 매핑: Agent Gateway를 게이트웨이와 동일한 프로젝트 및 리전에 있는 리전 Agent Registry 인스턴스와 연결합니다. 배포 패턴에 대한 자세한 내용은 Agent Gateway 배포 계획을 참조하세요.

표: Gemini Enterprise 앱 위치 및 Agent Registry 매핑

Gemini Enterprise 앱 위치	필수 Agent Gateway 리전	Agent Gateway에 필요한 Agent Registry 인스턴스
global	us-central1	us-central1(//agentregistry.googleapis.com/projects/PROJECT_ID/locations/us-central1)
us	us-central1	us-central1(//agentregistry.googleapis.com/projects/PROJECT_ID/locations/us-central1)
eu	europe-west1	europe-west1(//agentregistry.googleapis.com/projects/PROJECT_ID/locations/europe-west1)

Agent Gateway를 통해 Gemini Enterprise 트래픽 라우팅

중요: Agent Gateway를 사용 설정하면 LLM 호출을 포함한 모든 Gemini Enterprise 트래픽이 게이트웨이를 통해 라우팅됩니다. 그런 다음 승인 정책을 사용하여 이 트래픽을 보호할 수 있습니다.

Agent Gateway를 통해 Gemini Enterprise 트래픽을 라우팅하려면 다음 단계를 수행합니다.

1. Agent Gateway 리소스를 만들고 이전 섹션에서 선택한 리전과 레지스트리를 준수하는지 확인합니다. 자세한 내용은 Agent Gateway 설정을 참조하세요.

   게이트웨이 구성을 확인합니다. Network Services API를 사용하여 Agent Gateway 구성을 검색하고 설정을 검사합니다.

   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   "https://networkservices.googleapis.com/v1/projects/PROJECT_ID/locations/AGENT_GATEWAY_REGION/agentGateways/AGENT_GATEWAY_NAME"
   

   다음은 올바르게 구성된 게이트웨이의 출력 예시입니다.

   {
     "name": "projects/my-ge-project/locations/us-central1/agentGateways/my-egress-gateway",
     "description": "A full configuration for Agent Gateway for Gemini Enterprise egress",
     "googleManaged": {
       "governedAccessPath": "AGENT_TO_ANYWHERE"
     },
     "protocols": [
       "MCP"
     ],
     "registries": [
       "//agentregistry.googleapis.com/projects/my-ge-project/locations/us-central1"
     ]
   }
   

2. UpdateEngine API를 사용하여 게이트웨이를 Gemini Enterprise 앱에 바인딩합니다. 이 단계를 완료하면 모든 기존 에이전트 트래픽이 지정된 Agent Gateway를 통해 즉시 라우팅됩니다.

   콘솔

   1. Google Cloud 콘솔에서 Gemini Enterprise 페이지로 이동합니다.

      Gemini Enterprise

   2. Agent Gateway와 연결할 앱의 이름을 클릭합니다.

   3. 보안을 클릭합니다.

   4. 구성 탭의 Agent Gateway 구성에서 게이트웨이의 전체 리소스 이름을 입력합니다. projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME 형식을 사용합니다.

   5. 저장을 클릭합니다.

   REST

   1. 다음 요청을 사용하여 앱을 업데이트합니다.

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -H "X-Goog-User-Project: PROJECT_ID" \
      -d '{
        "agentGatewaySetting": {
          "defaultEgressAgentGateway": {
            "name": "projects/PROJECT_ID/locations/AGENT_GATEWAY_REGION/agentGateways/AGENT_GATEWAY_NAME"
          }
        }
      }' \
      "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/GE_APP_LOCATION/collections/default_collection/engines/GE_APP_ID?updateMask=agentGatewaySetting.defaultEgressAgentGateway.name"

      다음을 바꿉니다.

      • PROJECT_ID: 프로젝트 ID입니다.
      • AGENT_GATEWAY_REGION: Agent Gateway의 리전입니다.
      • AGENT_GATEWAY_NAME: Agent Gateway의 이름입니다.
      • ENDPOINT_LOCATION: GE_APP_LOCATION과 일치하는 API 엔드포인트의 멀티 리전 프리픽스입니다. global, us 또는 eu을 지정합니다. 예를 들어 eu 앱은 eu-discoveryengine.googleapis.com를 사용합니다. global 앱의 경우 프리픽스가 없는 discoveryengine.googleapis.com도 지원됩니다.
      • PROJECT_NUMBER: 프로젝트 번호.
      • GE_APP_LOCATION: Gemini Enterprise 앱의 위치입니다. global, us 또는 eu을 지정합니다.
      • GE_APP_ID: Gemini Enterprise 앱의 ID입니다.

   2. 앱 구성을 확인하려면 다음 명령어를 사용하여 구성을 검색하고 설정을 검사합니다.

      curl -s -X GET \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "X-Goog-User-Project: PROJECT_ID" \
      -H "Content-Type: application/json" \
      "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/GE_APP_LOCATION/collections/default_collection/engines/GE_APP_ID" \
      | jq '{name: .name, displayName: .displayName, agentGatewaySetting: .agentGatewaySetting}'
      

      다음을 바꿉니다.

      • PROJECT_ID: 프로젝트 ID입니다.
      • ENDPOINT_LOCATION: GE_APP_LOCATION과 일치하는 API 엔드포인트의 멀티 리전 프리픽스입니다. global, us 또는 eu을 지정합니다.
      • PROJECT_NUMBER: 프로젝트 번호.
      • GE_APP_LOCATION: Gemini Enterprise 앱의 위치입니다. global, us 또는 eu을 지정합니다.
      • GE_APP_ID: Gemini Enterprise 앱의 ID입니다.

      다음은 올바르게 구성된 앱의 출력 예시입니다.

      {
      "name": "projects/PROJECT_NUMBER/locations/GE_APP_LOCATION/collections/default_collection/engines/GE_APP_ID",
      "displayName": "GE_APP_ID",
      "agentGatewaySetting": {
        "defaultEgressAgentGateway": {
          "name": "projects/PROJECT_ID/locations/AGENT_GATEWAY_REGION/agentGateways/AGENT_GATEWAY_NAME"
        }
      }
      }
      

3. 이제 Gemini Enterprise 앱에 이그레스 거버넌스가 사용 설정되었지만 앱은 에이전트 레지스트리의 어떤 외부 리소스와 상호작용할 수 있는지 자동으로 알지 못합니다.

   선택한 에이전트, 엔드포인트, MCP 서버를 Gemini Enterprise 앱으로 명시적으로 가져와야 합니다. 가져온 리소스는 정확한 레지스트리 기반 리소스 이름을 사용하여 참조해야 합니다. 자세한 내용은 다음 가이드를 참조하세요.

   • 에이전트 레지스트리에서 MCP 서버 가져오기
   • Agent Registry에서 A2A 에이전트 가져오기

4. 이그레스가 올바르게 작동하는지 확인하려면 다음 단계를 수행합니다.

   1. Gemini Enterprise 웹 애플리케이션을 엽니다.
   2. 외부 도구를 트리거하도록 설계된 쿼리를 제출합니다(예: 'GitHub의 최근 문제 목록을 알려줘').
   3. 실행을 모니터링하여 응답이 성공적으로 검색되는지 확인합니다. 백그라운드에서 Gemini Enterprise 에이전트는 요청을 패키징하고, 구성된 승인 정책을 적용하는 Agent Gateway를 통해 라우팅하며, 대상에서 응답을 가져옵니다.

Gemini Enterprise 바인딩을 승인된 Agent Gateway로 제한

커스텀 조직 정책 제약 조건을 만들어 Gemini Enterprise 앱이 일부 또는 모든 Agent Gateway에 바인딩할 수 있는지 여부를 제한할 수 있습니다.

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

이 예시에서는 Gemini Enterprise 앱과 Agent Gateway 간의 모든 바인딩을 차단하는 커스텀 제약 조건을 만듭니다.

에이전트에서 모든 위치로

1. Agent-to-Anywhere 모드 (이그레스)에 대한 커스텀 제약 조건을 정의하려면 constraint-agent-gateway-egress.yaml이라는 파일을 만듭니다.

   다음 예시에서는 바인딩을 허용하지 않음으로써 엄격한 네트워크 격리를 적용하는 방법을 보여줍니다. condition 필드는 Agent Gateway 리소스가 지정된 경우 (필드가 있고 비어 있지 않음) 작업이 거부되도록 지정합니다.

   name: organizations/ORGANIZATION_ID/customConstraints/custom.disallowGeminiEnterpriseAgentGatewayBinding
   resource_types:
   
   
   
   discoveryengine.googleapis.com/Engine
   condition: >-
   has(resource.agentGatewaySetting.defaultEgressAgentGateway.name) &&
   resource.agentGatewaySetting.defaultEgressAgentGateway.name != ''
   actionType: DENY
   displayName: "Disallow all Agent Gateway Bindings for Discovery Engines"
   description: "To enforce strict network isolation, Discovery Engines are not permitted to bind to any Agent Gateway."

다음을 바꿉니다.

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

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

   gcloud org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH
   

   EGRESS_CONSTRAINT_PATH를 이전 단계에서 만든 커스텀 제약 조건 파일의 전체 경로로 바꿉니다.

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

   name: projects/PROJECT_ID/policies/custom.disallowGeminiEnterpriseAgentGatewayBinding
   spec:
   rules:
   
   
   
   enforce: true

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

4. 조직 정책을 시행합니다.

   gcloud org-policies set-policy EGRESS_POLICY_PATH
   

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

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

다음 단계

Codelab

Codelab: Agent Platform으로 에이전트 워크로드 관리

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

가이드

Agent Gateway에 대한 승인 위임

Agent Gateway의 승인을 IAP, Model Armor 또는 자체 커스텀 승인 서비스에 위임하는 방법을 알아봅니다.

가이드

Agent Gateway 모니터링

Agent Gateway를 모니터링하는 방법을 알아봅니다.

문제 해결

Agent Gateway 문제 해결

Agent Gateway 연결 문제를 해결하는 방법을 알아봅니다.