Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Model Armor를 Agent Gateway와 통합

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

Model Armor가 Agent Gateway를 통과하는 콘텐츠에서 정책 위반을 감지하면 이러한 이벤트를 로깅하도록 구성할 수 있습니다. Google Cloud 콘솔의 Model Armor 페이지에서 이러한 발견 항목을 확인할 수 있습니다 (Model Armor로 이동). 이러한 발견 항목은 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의 인라인 보호는 MCP 서버, OpenAI 형식을 따르는 서비스, 에이전트 게이트웨이를 통한 A2A와의 통합으로 제한됩니다.
인그레스 통합 호환성: Model Armor를 사용한 인라인 인그레스 보호는 ADK를 사용하여 빌드된 에이전트에서만 지원됩니다.

게이트웨이에서 Model Armor 구성

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

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

템플릿 이름을 기록해 둡니다.Google Cloud 콘솔에서 템플릿 이름을 복사하려면 템플릿 세부정보를 확인하고 템플릿 이름 옆에 있는 클립보드에 복사를 클릭합니다.
Model Armor 템플릿이 저장된 동일한 리전에 Agent Gateway를 설정합니다. 클라이언트-에이전트(인그레스) 게이트웨이의 경우 인그레스 트래픽에 대해 생성한 Model Armor 템플릿을 지정합니다. 에이전트-어디로든 (egress) 게이트웨이의 경우 egress 트래픽을 위해 만든 Model Armor 템플릿을 지정합니다. 두 트래픽 흐름에 동일한 템플릿을 사용할 수 있습니다.
적절한 서비스 에이전트에 필요한 IAM 역할을 부여합니다.
- 클라이언트에서 에이전트로 (인그레스): AI Platform Reasoning Engine 서비스 에이전트 서비스 에이전트에 다음 역할을 부여합니다.
  - 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입니다.
- 에이전트-애니웨어 (이그레스): 서비스 확장 프로그램 서비스 에이전트에 다음 역할을 부여합니다.
  - 게이트웨이가 포함된 프로젝트의 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 역할 부여를 참고하세요.

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

에이전트 게이트웨이 및 모델 아머 통합과 관련하여 수신 및 송신이라는 용어는 AI 에이전트의 상호작용 관점에서 사용됩니다.

인그레스 트래픽 (클라이언트-상담사): 클라이언트와 상담사 간의 커뮤니케이션 흐름을 나타냅니다. Model Armor는 클라이언트에서 에이전트로 전송되는 인바운드 요청과 에이전트에서 클라이언트로 다시 전송되는 아웃바운드 응답을 모두 보호할 수 있습니다.
이그레스 트래픽 (에이전트-임의 위치): 에이전트와 외부 시스템 간의 통신 흐름을 나타냅니다. Model Armor는 에이전트에서 외부 시스템으로 전송되는 발신 요청과 외부 시스템에서 에이전트로 전송되는 수신 응답을 모두 보호할 수 있습니다.

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

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

클라이언트 (최종 사용자 또는 호출 애플리케이션)에서 AI 에이전트로 전송되는 인바운드 요청입니다.
AI 에이전트가 클라이언트에 다시 보내는 응답입니다.

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

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

다른 모든 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는 전송되는 페이로드를 검사합니다. 차단되면 연결이 종료됩니다.
허용되면 요청이 외부 시스템으로 전송됩니다.
외부 시스템이 응답을 다시 보냅니다. 에이전트 게이트웨이가 이 수신 응답을 가로챕니다.
Model Armor는 대답 페이로드를 검사하고, Agent Gateway는 에이전트에 도달하도록 허용하거나 차단합니다.

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

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

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

트레이스 ID 사용

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

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

트레이스 ID는 다음 두 가지 방법으로 처리됩니다.

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

다음 코드 샘플은 streamQuery 메서드에 대한 요청에서 맞춤 추적 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: Google Cloud 프로젝트의 ID입니다.
- REASONING_ENGINE_ID: 추론 엔진의 ID입니다.

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

특정 트레이스 ID의 삭제 작업 로그를 보려면 로그 탐색기에서 다음 쿼리를 사용하세요.

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

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

연관 ID 사용

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

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