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

게이트웨이에서 Model Armor 구성

Model Armor를 사용하면 에이전트 내에 필터링 로직을 직접 구현하지 않고도 AI 에이전트가 보안 및 거버넌스 표준을 따르도록 할 수 있습니다. Agent Gateway로 Model Armor를 구성하면 Model Armor는 게이트웨이를 통과하는 모든 프롬프트와 대답을 검사하여 조직의 콘텐츠 보안 가드레일을 적용합니다. 이 기능을 사용하면 게이트웨이에서 관리하는 모든 에이전트에 콘텐츠 보안 가드레일을 일관되게 적용할 수 있습니다. Model Armor는 프롬프트 인젝션, 탈옥 시도, 민감한 정보 유출, 유해한 콘텐츠 생성과 같은 위험을 완화하는 데 도움이 됩니다. 자세한 내용은 Model Armor 필터를 참조하세요.

Model Armor 템플릿

게이트웨이에서 Model Armor를 구성하려면 AI 에이전트가 수신하고 반환하는 프롬프트와 응답을 검사하는 방법을 지정하는 템플릿을 만듭니다. 템플릿은 여러 안전 및 보안 카테고리에 대한 맞춤설정된 필터와 기준점을 제공합니다. 자세한 내용은 Model Armor 템플릿을 참조하세요.

Model Armor는 Agent Gateway에서 관리하는 통신 경로에 선별 기능을 직접 삽입합니다. Model Armor를 통해 콘텐츠를 전달하면 게이트웨이가 콘텐츠 보안 템플릿을 적용합니다. 템플릿에서 Model Armor를 구성하여 템플릿을 위반하는 콘텐츠를 수정하거나 차단할 수 있습니다.

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

Model Armor는 Agent Gateway를 통해 다음 트래픽 흐름을 보호할 수 있습니다.

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

Model Armor가 클라이언트-에이전트 트래픽 내에서 요청과 응답을 모두 평가하는 데 사용하는 템플릿을 정의합니다. 단일 템플릿을 양방향에 적용하거나 각 방향에 서로 다른 템플릿을 구성할 수 있습니다.

Model Armor는 다음을 선별할 때 템플릿을 따릅니다.

클라이언트 (최종 사용자 또는 호출 애플리케이션)에서 AI 에이전트로 들어오는 요청
AI 에이전트에서 클라이언트로 다시 전송되는 발신 응답

클라이언트가 에이전트에 프롬프트를 전송하면 Agent Gateway가 트래픽을 가로채고 정리를 위해 페이로드를 Model Armor로 전송합니다. Model Armor에서 ALLOW 판정을 내리면 Agent Gateway가 프롬프트를 AI 에이전트로 전송합니다. Model Armor에서 BLOCK 판정을 내리면 클라이언트에 오류가 발생하고 AI 에이전트에 도달하기 전에 흐름이 종료됩니다.

AI 에이전트가 요청을 처리하고 대답을 생성하면 Agent Gateway는 발신 스트림이 클라이언트에 도달하기 전에 가로챕니다. Model Armor가 대답을 평가하고 결과를 내립니다. 판정에 따라 Agent Gateway는 응답을 허용하거나 완전히 차단합니다.

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

Model Armor가 Agent-to-Anywhere 트래픽의 요청과 응답을 평가하는 데 사용하는 템플릿을 정의합니다. 단일 템플릿을 양방향에 적용하거나 각 방향에 서로 다른 템플릿을 구성할 수 있습니다.

Model Armor는 AI 에이전트와 외부 시스템 간의 통신을 검사할 때 다음을 포함한 템플릿을 따릅니다.

외부 대규모 언어 모델 (LLM)
서드 파티 AI 에이전트
모델 컨텍스트 프로토콜(MCP) 서버

AI 에이전트가 외부 시스템과 통신할 때 Agent Gateway는 이그레스 트래픽을 가로채고 Model Armor를 호출합니다. Model Armor는 설정한 이그레스 템플릿에 따라 페이로드를 평가합니다.

출력 데이터가 보안 정책을 위반하는 경우 Model Armor는 BLOCK 결과를 반환합니다. 그러면 Agent Gateway가 연결을 종료하여 유해하거나 민감한 정보가 LLM, 도구 또는 외부 AI 에이전트에 도달하지 못하도록 합니다.

시작하기 전에

Model Armor API가 아직 사용 설정되지 않은 경우 사용 설정합니다.

API 사용 설정에 필요한 역할

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

API 사용 설정하기

필요한 역할

Model Armor 템플릿을 만드는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Model Armor 관리자 (roles/modelarmor.admin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

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

Agent Gateway를 사용하는 데 필요한 역할은 Agent Gateway 문서의 필수 역할을 참조하세요.

게이트웨이를 통과하는 지원되는 페이로드와 지원되지 않는 페이로드에 대한 자세한 내용은 이 문서의 지원되는 페이로드와 지원되지 않는 페이로드를 참조하세요.

게이트웨이에서 Model Armor 구성

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

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

템플릿 이름을 기록해 둡니다.Google Cloud 콘솔에서 템플릿 이름을 복사하려면 템플릿 세부정보를 확인하고 템플릿 이름 옆에 있는 클립보드에 복사를 클릭합니다.

AI 에이전트 또는 Agent Gateway가 포함된 프로젝트와 다른 프로젝트에서 Model Armor 템플릿을 만들고 VPC 서비스 제어를 사용하는 경우 두 프로젝트가 동일한 VPC 서비스 제어 서비스 경계에 있어야 합니다.
Model Armor 템플릿이 저장된 리전과 동일한 리전에 Agent Gateway를 설정합니다. 클라이언트-에이전트(인그레스) 게이트웨이의 경우 인그레스 트래픽에 대해 만든 Model Armor 템플릿을 지정합니다. Agent-to-Anywhere (이그레스) 게이트웨이의 경우 이그레스 트래픽에 대해 만든 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 역할 부여를 참조하세요.

팁: Terraform (google_model_armor_template, google_model_armor_floorsetting, google_network_services_authz_extension, google_network_security_authz_policy)을 사용하여 단일 또는 다중 프로젝트 환경에서 이러한 리소스를 선언적으로 프로비저닝할 수 있습니다. 자세한 내용은 Model Armor 템플릿 만들기, 하한선 설정 구성, Model Armor에 승인 위임을 참조하세요.

선택사항: 배포 전 템플릿 유효성 검사

게이트웨이에 템플릿을 배포하기 전에 배포 전 검사를 실행하여 템플릿 구성이 보안 정책을 올바르게 적용하는지 확인할 수 있습니다.

테스트 프롬프트 집합을 사용하여 sanitizeUserPrompt 메서드를 직접 쿼리하여 템플릿을 검증할 수 있습니다. 이 배포 전 검사를 실행하는 방법과 확인된 테스트 프롬프트 목록에 대한 자세한 내용은 Model Armor 템플릿 테스트를 참조하세요.

요청 및 응답에서 민감한 정보 수정

Model Armor에 페이로드에서 주민등록번호, 전화번호와 같은 민감한 정보를 수정하도록 지시할 수 있습니다. 이 기능을 사용하려면 다음 단계를 따르세요.

Model Armor 템플릿에서 고급 Sensitive Data Protection 설정을 지정하고 익명화 템플릿을 포함합니다.
Model Armor 템플릿의 시정 조치 유형을 INSPECT_AND_BLOCK로 설정합니다.

INSPECT_AND_BLOCK 시행 유형을 사용하는 경우 다음 중 하나가 발생합니다.

페이로드가 Sensitive Data Protection 감지기만 위반하는 경우 Model Armor는 고급 Sensitive Data Protection 설정 및 익명화 템플릿에 따라 페이로드를 수정합니다.
페이로드가 여러 감지기를 위반하는 경우 Model Armor는 수정하지 않고 전체 페이로드를 차단합니다.

INSPECT_AND_BLOCK 대신 INSPECT_ONLY 시행 유형을 사용하는 경우 Model Armor는 페이로드를 수정하지 않습니다.

시행 유형 (INSPECT_ONLY 또는 INSPECT_AND_BLOCK)에 관계없이 Model Armor 로그는 고급 Sensitive Data Protection 설정 및 익명화 템플릿에 따라 수정됩니다.

Model Armor 감지기(필터라고도 함)의 전체 목록은 Model Armor 필터를 참조하세요.

지원되는 페이로드 및 지원되지 않는 페이로드

이 섹션에는 Model Armor가 정제하는 페이로드 유형이 나와 있습니다.

클라이언트에서 에이전트로 (인그레스) 트래픽

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

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

에이전트에서 모든 위치로 (이그레스) 트래픽

에이전트에서 다른 위치로의 (이그레스) 트래픽의 경우 다음 페이로드가 지원됩니다.

A2A 페이로드

Model Armor는 A2A v1 프로토콜의 다음 페이로드만 정제합니다.

메시지 보내기 작업
상담사 카드
확장 에이전트 카드 가져오기 작업
JSON-RPC 프로토콜 바인딩
HTTP+JSON/REST 프로토콜 바인딩

Model Armor는 정제 없이 다음 A2A 페이로드를 허용합니다.

v1 이전의 A2A 버전 페이로드
SendStreamingMessage
GetTask
ListTasks
CancelTask
SubscribeToTask
TaskPushNotificationConfig의 CRUD 메서드
A2A gRPC 프로토콜 바인딩 (유선 protobuf)을 사용하는 페이로드
A2A 오류 페이로드

MCP 페이로드

Model Armor는 다음 MCP 페이로드만 정제합니다.

tools/call 요청 및 응답
prompts/get 요청 및 응답
MCP 도구 실행 오류(악의적인 MCP 도구 작성자의 프롬프트 인젝션 대상)

Model Armor는 정제 없이 다음 페이로드를 허용합니다.

tools/list
resources/*
notifications/*
MCP용 스트리밍 가능 HTTP/SSE
MCP 프로토콜 오류 (예: 도구 실행 오류 이외의 모든 오류)

외부 LLM 페이로드

Model Armor는 openai.com의 GPT 모델과 OpenAI API 호환 LLM 서버 (예: vLLM)를 통한 기타 모델을 포함하는 OpenAI API 프로토콜 (이그레스)의 다음 페이로드만 정제합니다. 여기에 나열되지 않은 페이로드는 정제 없이 허용됩니다.

채팅 완료: 만들기, 삭제, 가져오기, 나열, 업데이트 (비스트리밍 변형만 해당)
채팅 메시지 가져오기
응답: 만들기, 가져오기, 삭제 (비스트리밍 변이만 해당)
OpenAI API 오류(vLLM 변형 포함)
기존 완료
기존 어시스턴트: 만들기, 삭제, 나열, 수정, 검색
기존 메시지: 만들기, 삭제, 나열, 수정, 검색
기존 대화목록: 만들기, 삭제, 수정, 검색
임베딩: 만들기

문서 심사

문서 또는 파일 업로드 (예: PDF)가 포함된 프롬프트 및 대답을 정제하는 것은 이 통합에서 지원되지 않습니다. 문서를 검사하려면 Model Armor REST API를 직접 호출합니다. 자세한 내용은 Model Armor 문서의 문서 선별을 참조하세요.

할당량 및 시스템 한도

할당량은 Model Armor 템플릿이 있는 프로젝트에서 사용됩니다. 게이트웨이가 다른 프로젝트에 있는 경우 게이트웨이 프로젝트에서도 ExternalProcessor 할당량이 사용됩니다.

Model Armor를 다른 서비스와 함께 사용할 때 적용되는 할당량에 대한 자세한 내용은 할당량 관리를 참조하세요.

입력 크기 및 토큰 한도를 포함한 Model Armor 할당량 및 시스템 한도에 대한 일반적인 내용은 Model Armor 문서의 할당량 및 시스템 한도를 참조하세요.

게이트웨이에서 Model Armor 구성 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

Model Armor 템플릿

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

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

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

시작하기 전에

필요한 역할

게이트웨이에서 Model Armor 구성

선택사항: 배포 전 템플릿 유효성 검사

요청 및 응답에서 민감한 정보 수정

지원되는 페이로드 및 지원되지 않는 페이로드

클라이언트에서 에이전트로 (인그레스) 트래픽

에이전트에서 모든 위치로 (이그레스) 트래픽

A2A 페이로드

MCP 페이로드

외부 LLM 페이로드

문서 심사

할당량 및 시스템 한도

다음 단계

게이트웨이에서 Model Armor 구성