Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Model Armor를 Agent Gateway와 통합

Gemini Enterprise Agent Platform은 엔터프라이즈급 AI 에이전트를 빌드하고 관리하기 위한 플랫폼입니다. Agent Gateway는 AI 에이전트가 환경 내에서 그리고 외부 에이전트, AI 애플리케이션, LLM과 연결하고 상호작용하는 방식을 관리, 보호, 제어하는 컨트롤 플레인 역할을 합니다. Google Cloud Model Armor와 Agent Gateway를 통합하면 Model Armor의 검사 기능이 Gemini Enterprise Agent Platform에서 관리하는 통신 경로에 직접 삽입됩니다. 콘텐츠가 Agent Gateway를 통과하면 Model Armor를 호출하여 미리 정의된 보안 템플릿을 적용합니다. 정책을 위반하는 콘텐츠를 차단하고 수정하도록 템플릿을 구성하거나 콘텐츠만 검사하고 감지된 위반사항을 로깅하도록 템플릿을 구성할 수 있습니다. 이렇게 하면 프롬프트 인젝션, 탈옥, 유해한 콘텐츠 노출, 민감한 정보 유출과 같은 위험을 완화할 수 있습니다.

Model Armor가 Agent Gateway를 통과하는 콘텐츠에서 정책 위반을 감지하면 이러한 이벤트를 로깅하도록 구성할 수 있습니다. 콘솔의 Model Armor 페이지에서 이러한 발견 항목을 확인할 수 있습니다 (Model Armor로 이동). Google Cloud 이러한 발견 항목은 Security Command Center에도 표시됩니다. 자세한 내용은 콘솔에서 발견 항목 검토를 참조하세요.Google Cloud

실시간 스트리밍 모드를 사용하는 경우 Model Armor는 스트림에서 무제한 토큰을 지원하므로 장기 실행 상호작용 및 모델 응답에 적합합니다.

제한사항

Model Armor를 Agent Gateway와 통합할 때는 다음 제한사항을 고려하세요.

에이전트 스트리밍 지원: Model Armor는 에이전트 개발 키트로 빌드된 에이전트에 대해 streamQuery 메서드를 사용한 스트리밍 정리만 지원합니다.
프로젝트 간 템플릿 사용: 한 프로젝트에서 Model Armor 템플릿을 사용하여 다른 프로젝트의 Agent Gateway와 같은 서비스의 요청을 정리하는 경우 템플릿을 호스팅하는 프로젝트와 호출 서비스를 호스팅하는 프로젝트 모두에서 Model Armor 의 API 할당량이 충분해야 합니다. 자세한 내용은 할당량 관리를 참조하세요.
리전 정렬: Model Armor와 통합되는 서비스는 동일한 Google Cloud 리전 내에 배포해야 합니다. Model Armor에 대한 리전 간 호출은 지원되지 않습니다.
이그레스 통합 호환성: 이그레스 트래픽에 대한 Model Armor's 인라인 보호는 MCP 서버, OpenAI 형식을 따르는 서비스, Agent Gateway를 통한 A2A와의 통합으로 제한됩니다.
인그레스 통합 호환성: Model Armor를 사용한 인라인 인그레스 보호는 ADK를 사용하여 빌드된 에이전트에만 지원됩니다.

게이트웨이에서 Model Armor 구성

게이트웨이에서 Model Armor를 구성하려면 다음 단계를 따르세요.

Model Armor API를 Model Armor 템플릿을 만들려는 프로젝트에서 사용 설정합니다.
게이트웨이를 추가할 계획인 동일한 리전에서 하나 이상의 Model Armor 템플릿을 만듭니다. 인그레스 및 이그레스 트래픽 모두에 동일한 템플릿을 사용할 수 있습니다.

템플릿 이름을 기록해 둡니다. 콘솔에서 템플릿 이름을 복사하려면 템플릿의 세부정보를 보고 템플릿 이름 옆에 있는 클립보드에 복사를 클릭합니다.Google Cloud
Model Armor 템플릿이 저장된 동일한 리전에서 Agent Gateway를 설정합니다. 클라이언트에서 에이전트로 (인그레스) 게이트웨이의 경우 인그레스 트래픽을 위해 만든 Model Armor 템플릿을 지정합니다. 에이전트에서 모든 위치로 (이그레스) 게이트웨이의 경우 이그레스 트래픽을 위해 만든 Model Armor 템플릿을 지정합니다. 두 트래픽 흐름 모두에 동일한 템플릿을 사용할 수 있습니다.
적절한 서비스 계정에 필요한 IAM 역할을 부여합니다.
- 클라이언트에서 에이전트로 (인그레스): AI Platform Reasoning Engine Service Agent 서비스 계정에 다음 역할을 부여합니다.
  - AI 에이전트가 포함된 프로젝트의 Model Armor 콜아웃 사용자 (roles/modelarmor.calloutUser) 역할
  - Model Armor 템플릿이 포함된 프로젝트의 Model Armor 사용자 (roles/modelarmor.user) 역할
```
gcloud projects add-iam-policy-binding AGENT_RUNTIME_PROJECT_ID \
    --member=serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com \
    --role=roles/modelarmor.user
```
  다음을 바꿉니다.
  - AGENT_RUNTIME_PROJECT_ID: 에이전트를 만든 프로젝트의 프로젝트 ID
  - AGENT_RUNTIME_PROJECT_NUMBER: 에이전트를 만든 프로젝트의 프로젝트 번호
  - MODEL_ARMOR_PROJECT_ID: Model Armor 템플릿이 포함된 프로젝트의 프로젝트 ID
- 에이전트에서 모든 위치로 (이그레스): Agent Gateway 서비스 계정에 다음 역할을 부여합니다.
  - 게이트웨이가 포함된 프로젝트의 Model Armor 콜아웃 사용자 (roles/modelarmor.calloutUser) 및 서비스 사용량 소비자 (roles/serviceusage.serviceUsageConsumer) 역할
  - Model Armor 템플릿이 포함된 프로젝트의 Model Armor 사용자 (roles/modelarmor.user) 역할
```
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.user
```
  다음을 바꿉니다.
  - GATEWAY_PROJECT_ID: 게이트웨이를 만든 프로젝트의 프로젝트 ID
  - GATEWAY_PROJECT_NUMBER: 게이트웨이를 만든 프로젝트의 프로젝트 번호
  - MODEL_ARMOR_PROJECT_ID: Model Armor 템플릿이 포함된 프로젝트의 프로젝트 ID
  자세한 내용은 Model Armor에 승인 위임을 참조하세요.
역할을 부여하는 방법에 관한 일반적인 내용은 단일 IAM 역할 부여를 참조하세요.

인그레스 및 이그레스 트래픽

Agent Gateway 및 Model Armor 통합의 컨텍스트에서 인그레스 및 이그레스 라는 용어는 AI 에이전트 상호작용의 관점에서 사용됩니다.

인그레스 트래픽 (클라이언트에서 에이전트로): 클라이언트와 에이전트 간의 통신 흐름을 나타냅니다. Model Armor는 클라이언트에서 에이전트로의 수신 요청과 에이전트에서 클라이언트로의 발신 응답을 모두 보호할 수 있습니다.
이그레스 트래픽 (에이전트에서 모든 위치로): 에이전트와 외부 시스템 간의 통신 흐름을 나타냅니다. Model Armor는 에이전트에서 외부 시스템으로의 발신 요청과 외부 시스템에서 에이전트로의 수신 응답을 모두 보호할 수 있습니다.

클라이언트에서 에이전트로 (인그레스) 보호

Model Armor가 평가하는 데 사용하는 템플릿을 정의합니다.

클라이언트 (최종 사용자 또는 호출 애플리케이션)에서 AI 에이전트로의 수신 요청
AI 에이전트에서 클라이언트로의 발신 응답

단일 템플릿을 양방향으로 적용하거나 각 템플릿에 대해 다른 템플릿을 구성할 수 있습니다.

ADK 프로토콜을 사용하는 클라이언트에서 에이전트로 (인그레스) 트래픽의 경우 Model Armor는 reasoningEngines.streamQuery 에이전트 개발 키트 (ADK)를 사용하여 빌드되고 Agent Runtime에서 실행되는 에이전트에 대해서만 요청 및 응답을 정리합니다.

다른 모든 ReasoningEngine 페이로드 및 ReasoningEngine 오류 응답은 Model Armor로 전송되지 않습니다. ADK가 아닌 페이로드 (예: Langchain 페이로드)도 Model Armor로 전송되지 않습니다.

클라이언트에서 에이전트로의 트래픽 흐름

클라이언트가 에이전트에 프롬프트를 보냅니다. Agent Gateway가 요청을 가로채고 페이로드를 Model Armor로 보냅니다.
Model Armor가 요청을 검사합니다. 차단되면 클라이언트가 오류를 수신합니다.
허용되면 요청이 AI 에이전트에 도달합니다.
AI 에이전트가 응답을 생성합니다. Agent Gateway는 이 응답이 클라이언트에 도달하기 전에 가로챕니다.
Model Armor가 응답을 검사하고 Agent Gateway는 판결에 따라 응답을 허용하거나 차단합니다.

에이전트에서 모든 위치로 (이그레스) 보호

Model Armor가 평가하는 데 사용하는 템플릿을 정의합니다.

AI 에이전트에서 외부 시스템으로의 발신 요청
외부 시스템에서 AI 에이전트로의 수신 응답

이 보호는 다음을 포함한 시스템과의 통신에 적용됩니다.

외부 LLM 및 서드 파티 AI 에이전트
모델 컨텍스트 프로토콜 (MCP) 서버
기타 AI 에이전트

에이전트에서 모든 위치로의 트래픽 흐름

AI 에이전트가 외부 시스템에 대한 요청을 시작합니다. Agent Gateway가 발신 트래픽을 가로챕니다.
Model Armor가 발신 페이로드를 검사합니다. 차단되면 연결이 종료됩니다.
허용되면 요청이 외부 시스템으로 전송됩니다.
외부 시스템이 응답을 다시 보냅니다. Agent Gateway가 이 수신 응답을 가로챕니다.
Model Armor가 응답 페이로드를 검사하고 Agent Gateway는 에이전트에 도달하도록 허용하거나 차단합니다.

자세한 내용은 게이트웨이에서 Model Armor 구성을 참조하세요.

스트리밍 요청 추적 및 디버깅

스트리밍 요청의 추적 및 디버깅을 용이하게 하기 위해 Model Armor는 연관 ID와 trace ID를 사용합니다.

trace ID 사용

trace ID는 분산 시스템의 여러 서비스를 이동할 때 단일 요청의 모든 이벤트를 연결합니다. 여기에는 Model Armor가 Agent Gateway 리소스의 요청 경로 내에서 적용하는 보안 적용이 포함됩니다.

각 trace에는 하나 이상의 스팬이 포함되며 각 스팬 ID는 trace 내의 특정 작업 또는 작업 단위를 나타냅니다. 요청 실행 중에 생성된 로그는 작업을 수행하는 작업의 특정 스팬 ID와 연결됩니다.

trace ID는 두 가지 방법으로 처리됩니다.

자동: Google Cloud Observability가 사용 설정되면 Agent Gateway 가 trace ID를 자동으로 생성하고 시스템을 통해 전파합니다.
사용자 제공: 요청에서 traceparent HTTP 헤더를 사용하여 자체 trace ID를 제공하여 시스템 생성 trace ID를 재정의할 수 있습니다.

다음 코드 샘플은 streamQuery 메서드에 대한 요청에서 커스텀 trace ID를 전달하는 방법을 보여줍니다.
```
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "traceparent: 00-98adffecc8dd095968a06c44216190f6-5b565a8342378cd7-01" \
  "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID:streamQuery?alt=sse"
```
다음을 바꿉니다.
- LOCATION: 추론 엔진이 있는 리전
- PROJECT_ID: 프로젝트의 ID Google Cloud
- REASONING_ENGINE_ID: 추론 엔진의 ID

trace ID를 사용하는 것이 호출자에서 Agent Gateway를 거쳐 Model Armor 및 다운스트림 에이전트에 이르기까지 로그와 trace를 엔드 투 엔드로 연결하는 데 권장되는 방법입니다. 이는 디버깅, 보안 작업 이해, 성능 모니터링에 필수적입니다. 자세한 내용은 Model Armor trace 스팬 보기를 참조하세요.

특정 trace ID의 정리 작업 로그를 보려면 로그 탐색기에서 다음 쿼리를 사용합니다.

jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
trace:TRACE_ID

TRACE_ID를 요청의 trace ID로 바꿉니다.

연관 ID 사용

연관 ID는 초기 요청에서 최종 응답에 이르기까지 단일 스트리밍 정리 세션과 관련된 Cloud Logging의 모든 로그 항목을 연결합니다. 이는 주로 Model Armor 로그 내에서, 특히 인그레스 스트리밍 세션에 사용되는 내부 식별자입니다. 자세한 내용은 로그 및 관련 이벤트 연결을 참조하세요.

Model Armor를 Agent Gateway와 통합 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.