시맨틱 거버넌스 정책 구성

시맨틱 거버넌스 정책 및 정책 엔진 구성

이 섹션에서는 인프라 준비에서 정책 작성으로의 전환을 다룹니다.

기본 요건

시맨틱 거버넌스 정책을 구성하기 전에 다음 단계를 완료하세요.

필요한 API 사용 설정

시작하기 전에 시맨틱 거버넌스 정책 및 네트워킹 구성요소에 필요한 API를 사용 설정하세요.

gcloud services enable \
    aiplatform.googleapis.com \
    agentregistry.googleapis.com \
    networkservices.googleapis.com \
    networksecurity.googleapis.com \
    compute.googleapis.com \
    dns.googleapis.com \
    --project=PROJECT_ID

Vertex AI 서비스 계정에 IAM 권한 부여 (Google 관리 바인딩만 해당)

프로비저닝 중에 Google 관리 바인딩 옵션을 사용하는 경우 Vertex AI 서비스 계정 (P4SA)에 프로젝트에서 Private Service Connect (PSC) 엔드포인트(roles/compute.networkAdmin)와 DNS 레코드 세트 (roles/dns.admin)를 만드는 데 필요한 역할을 부여합니다. 자체 관리 바인딩 옵션을 사용하는 경우 이러한 네트워크 리소스를 직접 만들기 때문에 이 단계를 건너뛸 수 있습니다.

서비스 ID를 만들고 (멱등성) 역할을 부여합니다.

export PROJECT_NUM=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")

gcloud beta services identity create \
    --service=aiplatform.googleapis.com \
    --project=PROJECT_ID

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-${PROJECT_NUM}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/compute.networkAdmin"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-${PROJECT_NUM}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/dns.admin"

해당 삭제 명령어는 정리 섹션의 IAM 바인딩 삭제에 있습니다.

에이전트 자격 요건

Cloud de Confiance 콘솔의 시맨틱 거버넌스 정책의 에이전트 선택기에 표시되려면 에이전트의 추론 엔진이 identity_type=AGENT_IDENTITY 및 agent_gateway_config이 모두 설정된 상태로 배포되어야 합니다. 둘 중 하나가 누락되면 Cloud de Confiance 콘솔에서 선택기에서 상담사를 필터링합니다. 대신 API와 gcloud에서 명시적인 오류를 반환합니다.

이러한 요구사항을 충족하는 에이전트를 배포하려면 Agent Gateway를 통해 Agent Runtime 트래픽 라우팅을 따르세요. 두 필드는 기존 추론 엔진에서 변경할 수 없으므로 이러한 필드 없이 배포된 에이전트는 다시 배포해야 합니다. 패치는 작동하지 않습니다.

기존 에이전트가 자격 요건을 충족하는지 확인하려면 추론 엔진의 spec.effectiveIdentity이 agents.global.로 시작하는지 확인하세요.

gcloud ai reasoning-engines describe REASONING_ENGINE_ID \
    --region=LOCATION \
    --project=PROJECT_ID \
    --format='value(spec.effectiveIdentity)' \
    | grep -q '^agents.global.' \
    && echo "Eligible" || echo "Not eligible"

지원되는 위치

시맨틱 거버넌스 정책 엔진 및 시맨틱 거버넌스 정책은 다음 리전 위치에서 지원됩니다.

프로비저닝 및 지원

시맨틱 거버넌스 정책 엔진을 사용 설정합니다. 이렇게 하면 필요한 런타임 환경이 프로비저닝됩니다. 프로비저닝은 일반적으로 완료하는 데 약 2~3분이 걸립니다. 하지만 수요가 많거나 웜업 풀이 다시 채워지는 중에는 프로비저닝에 최대 20분이 걸릴 수 있습니다. 프로비저닝을 위해 다음 옵션 중 하나를 선택합니다.

• Google 관리 바인딩: Google은 Cloud de Confiance by S3NS 프로젝트에서 기본 네트워크 리소스를 만들고 수명 주기를 자동으로 관리합니다.
• 자체 관리 바인딩: 필요한 네트워크 리소스 (network, subnetwork, dnsZoneName)를 Cloud de Confiance by S3NS 프로젝트에서 직접 만들고 관리합니다.

프로비저닝을 완료한 후 정책 엔진을 Agent Gateway에 연결해야 합니다.

Google 관리 바인딩

curl -X PATCH \
    "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/semanticGovernancePolicyEngine?updateMask=gatewayConfigs" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{ "gatewayConfigs": {
        "GATEWAY_NAME": {
          "network": "NETWORK_NAME",
            "subnetwork": "SUBNETWORK_NAME",
            "dnsZoneName": "DNS_NAME" }
        }
      }'

gcloud beta ai semantic-governance-policy-engine update \
--location=LOCATION \
--project=PROJECT_ID \
--gateway-config="name='GATEWAY_NAME',network=NETWORK_NAME,subnetwork=SUBNETWORK_NAME,dns-zone-name=DNS_NAME"

다음을 바꿉니다.

• GATEWAY_NAME을 고유한 게이트웨이 이름으로 바꿉니다.
• DNS_NAME을 사용할 비공개 DNS 영역의 이름으로 바꿉니다.
• PROJECT_ID을 Cloud de Confiance by S3NS 프로젝트 ID (projects/PROJECT_ID/global/networks/default)로 바꿉니다. 맞춤 네트워크와 서브넷을 사용하는 경우 전체 network 및 subnetwork 리소스 경로를 적절하게 바꿉니다.

자동으로 생성된 DNS 호스트 이름 가져오기

Google 관리 바인딩으로 엔진을 프로비저닝하면 Google에서 자동으로 Private Service Connect (PSC) 엔드포인트를 만들고 비공개 DNS 영역에 DNS A 레코드를 등록합니다. 이 레코드의 FQDN은 SGP_DNS_HOSTNAME 역할을 하며 게이트웨이 구성의 dnsRecord 출력 전용 필드에 입력됩니다.

자동으로 생성된 DNS 호스트 이름을 가져오려면 다음 안내를 따르세요.

gcloud beta ai semantic-governance-policy-engine describe \
    --location=LOCATION \
    --project=PROJECT_ID

curl "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/semanticGovernancePolicyEngine" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

대답에서 gatewayConfigs.GATEWAY_NAME.dnsRecord 아래의 dnsRecord 필드를 찾습니다. 이 FQDN을 저장합니다. 정책 엔진을 Agent Gateway에 연결할 때 SGP_DNS_HOSTNAME로 필요합니다.

자체 관리형 바인딩

curl  -X PATCH "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/semanticGovernancePolicyEngine" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "projects/PROJECT_ID/locations/LOCATION/semanticGovernancePolicyEngine"
    }'

gcloud beta ai semantic-governance-policy-engine update \
    --location=LOCATION \
    --project=PROJECT_ID

이 명령어는 장기 실행 작업을 반환합니다. 응답의 name 값으로 OPERATION를 대체하여 작업 상태를 폴링할 수 있습니다.

curl "https://LOCATION-aiplatform.googleapis.com/v1beta1/OPERATION" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json"

또는 state 필드가 ACTIVE를 반환할 때까지 전체 엔진 상태를 확인합니다.

curl "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/semanticGovernancePolicyEngine" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json"

네트워크 구성 (자체 관리형만 해당)

정책 엔진이 프로비저닝된 후 Agent Gateway가 정책 엔진과 통신하는 데 필요한 네트워킹 구성요소를 구성합니다.

Google 관리 경로의 경우 Google에서 Google 관리 테넌트 프로젝트에 PSC 엔드포인트를 자동으로 만들지만 자체 관리 경로의 경우 자체 Cloud de Confiance by S3NS 프로젝트에서 PSC 엔드포인트를 수동으로 만들고 관리해야 합니다.

1. VPC 네트워크 및 서브넷 프로비저닝

이 단계에서는 에이전트 트래픽을 위한 VPC 네트워크, 서브넷, 프록시 전용 서브넷을 만듭니다. 표시된 IP 범위 (10.11.12.0/24 및 10.11.13.0/24)는 예시입니다. 네트워크 설계에 적합한 RFC 1918 비공개 범위를 사용할 수 있습니다.

1. VPC 네트워크를 만듭니다.

   gcloud compute networks create NETWORK_NAME \
       --subnet-mode=auto \
       --project=PROJECT_ID
   

   NETWORK_NAME을 VPC 네트워크 이름 (예: agent-network)으로 바꿉니다.

2. 서브넷을 만듭니다.

   gcloud compute networks subnets create SUBNET_NAME \
       --network=NETWORK_NAME \
       --region=LOCATION \
       --range=10.11.12.0/24 \
       --project=PROJECT_ID
   

   SUBNET_NAME을 서브넷 이름 (예: agent-subnet)으로 바꿉니다.

3. 프록시 전용 서브넷을 만듭니다 (관리형 부하 분산기에 필요).

   gcloud compute networks subnets create PROXY_SUBNET_NAME \
       --network=NETWORK_NAME \
       --region=LOCATION \
       --range=10.11.13.0/24 \
       --purpose=REGIONAL_MANAGED_PROXY --role=ACTIVE \
       --project=PROJECT_ID
   

   PROXY_SUBNET_NAME을 프록시 전용 서브넷의 이름 (예: agent-proxy-subnet)으로 바꿉니다.

2. 비공개 DNS 영역 프로비저닝

에이전트 게이트웨이가 정책 엔진의 호스트 이름을 확인할 수 있도록 비공개 DNS 영역을 만듭니다.

gcloud dns managed-zones create DNS_ZONE_NAME \
    --description="Private zone for my internal agentic VPC services" \
    --dns-name="internal.example.com." \
    --visibility=private \
    --networks=NETWORK_NAME \
    --project=PROJECT_ID

Replace the following:

• DNS_ZONE_NAME: DNS 영역의 이름 (예: my-private-zone)
• internal.example.com.: 후행 점을 포함한 영역의 DNS 이름입니다.

3. 네트워크 연결 만들기

Agent Gateway가 VPC의 리소스에 연결할 수 있도록 네트워크 연결을 만듭니다. 연결 환경설정은 ACCEPT_AUTOMATIC로 설정해야 합니다.

gcloud compute network-attachments create NETWORK_ATTACHMENT_NAME \
    --region=LOCATION \
    --subnets=SUBNET_NAME \
    --connection-preference=ACCEPT_AUTOMATIC \
    --project=PROJECT_ID

Replace the following:

• NETWORK_ATTACHMENT_NAME: 네트워크 연결의 이름입니다 (예: sgp-nw-attachment).
• SUBNET_NAME: 1단계에서 만든 서브넷입니다.

4. 고정 IP, PSC 엔드포인트, DNS 레코드 만들기

고정 IP 주소를 예약하고, 정책 엔진의 서비스 연결을 가리키는 Private Service Connect (PSC) 엔드포인트를 만들고, DNS 레코드를 만들어 연결할 수 있도록 합니다.

# Reserve a static IP address
gcloud compute addresses create STATIC_IP_NAME \
    --region=LOCATION \
    --subnet=SUBNET_NAME \
    --purpose=GCE_ENDPOINT \
    --project=PROJECT_ID

# Capture the reserved IP address
IP=$(gcloud compute addresses describe STATIC_IP_NAME \
    --region=LOCATION \
    --project=PROJECT_ID \
    --format=value(address))

# Create the PSC endpoint
gcloud compute forwarding-rules create PSC_ENDPOINT_NAME \
    --region=LOCATION \
    --network=NETWORK_NAME \
    --address=STATIC_IP_NAME \
    --target-service-attachment=PSC_SERVICE_ATTACHMENT \
    --project=PROJECT_ID

# Create a DNS A record for the policy engine
gcloud dns record-sets create SGP_DNS_HOSTNAME \
    --zone=DNS_ZONE_NAME \
    --type=A \
    --ttl=300 \
    --rrdatas=$IP \
    --project=PROJECT_ID

다음을 바꿉니다.

• STATIC_IP_NAME: 예약된 IP 주소의 이름입니다 (예: sgp-psc-ip).
• PSC_ENDPOINT_NAME: PSC 엔드포인트의 이름입니다 (예: sgp-psc-endpoint).
• PSC_SERVICE_ATTACHMENT: 프로비저닝 응답에서 저장된 pscServiceAttachment 값입니다.
• SGP_DNS_HOSTNAME: 비공개 DNS 영역의 호스트 이름으로, LOCATION.DNS_ZONE_SUFFIX 형식입니다. 여기서 DNS_ZONE_SUFFIX은 비공개 DNS 영역을 만들 때 지정한 DNS 이름입니다. 예를 들어 위치가 us-west1이고 DNS 영역 서픽스가 internal.example.com이면 us-west1.internal.example.com을 사용합니다.

5. Agent Gateway에서 VPC 연결 구성

네트워크 리소스를 만든 후에는 비공개 네트워크를 통해 정책 엔진에 연결할 수 있도록 Agent Gateway에 네트워크 연결 및 DNS 피어링을 등록해야 합니다.

자세한 내용은 Agent Gateway 설정 가이드의 VPC 연결 구성을 참고하세요. 최소한 다음을 충족해야 합니다.

• 3단계에서 만든 네트워크 연결을 Agent Gateway 이그레스 구성에 등록합니다.
• 4단계에서 만든 비공개 DNS 호스트 이름을 게이트웨이에서 확인할 수 있도록 DNS 피어링을 등록합니다.

정책 엔진을 Agent Gateway에 연결

네트워크가 구성된 후에는 Agent Gateway가 평가를 위해 트래픽을 정책 엔진으로 전달할 수 있도록 승인 확장 프로그램과 승인 정책을 만들어야 합니다.

1. 승인 확장 프로그램 만들기: 정책 엔진의 DNS 호스트 이름을 가리키는 승인 확장 프로그램을 만듭니다. 네트워크 구성 (4단계)에서 DNS 레코드를 만든 것과 동일한 SGP_DNS_HOSTNAME를 사용합니다. 이는 Agent Gateway가 평가를 위해 정책 엔진에 트래픽을 전송하는 메커니즘입니다.

   gcloud

   YAML 파일 (authz-ext.yaml)에서 확장 프로그램 구성을 정의하고 가져옵니다.

   name: AUTHZ_EXTENSION_NAME
   service: SGP_DNS_HOSTNAME
   authority: SGP_DNS_HOSTNAME
   failOpen: false
   loadBalancingScheme: LOAD_BALANCING_SCHEME_UNSPECIFIED
   

   gcloud service-extensions authz-extensions import AUTHZ_EXTENSION_NAME \
       --source=authz-ext.yaml \
       --location=LOCATION \
       --project=PROJECT_ID
   

   REST

   curl -X POST \
       "https://networkservices.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/authzExtensions?authzExtensionId=AUTHZ_EXTENSION_NAME" \
       -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
       -H "Content-Type: application/json" \
       -d '{
         "service": "SGP_DNS_HOSTNAME",
         "authority": "SGP_DNS_HOSTNAME",
         "failOpen": false,
         "loadBalancingScheme": "LOAD_BALANCING_SCHEME_UNSPECIFIED"
       }'
   

   SGP_DNS_HOSTNAME을 네트워크 구성 (4단계)에서 A 레코드를 만든 DNS 호스트 이름으로 바꿉니다.

   이 명령어는 장기 실행 작업을 반환합니다. 작업이 완료될 때까지 기다린 후 계속 진행합니다.

2. 승인 정책 만들기: 확장 프로그램을 Agent Gateway에 바인딩하는 승인 정책을 만듭니다. 이렇게 하면 Agent Gateway가 평가를 위해 정책 엔진을 통해 트래픽을 전송합니다.

   gcloud

   YAML 파일 (authz-policy.yaml)에서 승인 정책 구성을 정의하고 가져옵니다.

   name: AUTHZ_POLICY_NAME
   target:
     loadBalancingScheme: LOAD_BALANCING_SCHEME_UNSPECIFIED
     resources:
     - projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME
   httpRules:
   - to:
       operations:
       - paths:
         - prefix: /
     when: "!request.headers['content-type'].startsWith('application/grpc') && (request.path.endsWith(':generateContent') || request.path.endsWith(':streamGenerateContent'))"
   action: CUSTOM
   policyProfile: CONTENT_AUTHZ
   customProvider:
     authzExtension:
       resources:
       - projects/PROJECT_ID/locations/LOCATION/authzExtensions/AUTHZ_EXTENSION_NAME
   

   gcloud network-security authz-policies import AUTHZ_POLICY_NAME \
       --source=authz-policy.yaml \
       --location=LOCATION \
       --project=PROJECT_ID
   

   REST

   curl -X POST \
       "https://networksecurity.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/authzPolicies?authzPolicyId=AUTHZ_POLICY_NAME" \
       -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
       -H "Content-Type: application/json" \
       -d '{
         "target": {
           "loadBalancingScheme": "LOAD_BALANCING_SCHEME_UNSPECIFIED",
           "resources": ["projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"]
         },
         "httpRules": [{
           "to": {
             "operations": [{"paths": [{"prefix": "/"}]}]
           },
           "when": "!request.headers['"'"'content-type'"'"'].startsWith('"'"'application/grpc'"'"') && (request.path.endsWith('"'"':generateContent'"'"') || request.path.endsWith('"'"':streamGenerateContent'"'"'))"
         }],
         "action": "CUSTOM",
         "policyProfile": "CONTENT_AUTHZ",
         "customProvider": {
           "authzExtension": {
             "resources": ["projects/PROJECT_ID/locations/LOCATION/authzExtensions/AUTHZ_EXTENSION_NAME"]
           }
         }
       }'
   

   이 명령어는 장기 실행 작업을 반환합니다. 작업이 완료될 때까지 기다린 후 계속 진행합니다.

정책 만들기

정책 엔진이 활성화되면 에이전트의 기술적 및 행동적 가이드라인을 정의할 수 있습니다.

1. 범위 정의: 정책이 상담사가 취하는 모든 조치에 적용되는지 아니면 특정 도구를 타겟팅하는지 결정합니다.
2. 제약 조건 작성: 비즈니스 규칙을 영어로 제공합니다.

gcloud alpha agent-registry agents list \
    --project=PROJECT_ID \
    --location=LOCATION

gcloud config set api_endpoint_overrides/aiplatform \
    https://LOCATION-aiplatform.googleapis.com/

gcloud beta ai semantic-governance-policies create POLICY_ID \
    --location=LOCATION \
    --display-name="Semantic governance policy for ShippingAgent-1" \
    --description="Applies to all tool calls from the Cymbal shipping assistant agent" \
    --agent=projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID \
    --natural-language-constraint="Always use UPS as the shipping provider for shipments within the USA. Always use DHL as the shipping provider for shipments within the EU." \
    --project=PROJECT_ID

gcloud beta ai semantic-governance-policies create POLICY_ID \
    --location=LOCATION \
    --display-name="Semantic governance policy for ShippingAgent-1" \
    --agent=projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID \
    --natural-language-constraint="Always use UPS as the shipping provider for shipments within the USA. Always use DHL as the shipping provider for shipments within the EU." \
    --agent-response-denial-message="Sorry, I can only book shipments through the approved carriers for your region." \
    --project=PROJECT_ID

gcloud alpha agent-registry mcp-servers list \
    --project=PROJECT_ID \
    --location=LOCATION

gcloud beta ai semantic-governance-policies create POLICY_ID \
    --location=LOCATION \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --agent=projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID \
    --mcp-tools="mcp-server=MCP_SERVER,tools=TOOL_NAME" \
    --natural-language-constraint="NLC_TEXT" \
    --project=PROJECT_ID

정책이 여러 개인 거부 메시지

단일 요청으로 인해 여러 정책에서 거부가 트리거되면 정책 엔진은 사용자에게 응답을 반환하기 전에 해당 정책에 구성된 거부 메시지를 결합합니다. 다음 동작이 적용됩니다.

• 거부 판정이 있는 각 정책의 거부 메시지는 빈 줄로 구분되어 함께 표시됩니다.
• 중복 메시지는 한 번만 표시됩니다.
• 일부 트리거 정책에는 거부 메시지가 구성되어 있고 다른 정책에는 구성되어 있지 않은 경우, 거부 메시지가 없는 정책을 포괄하기 위해 일반적인 문구인 '다른 비즈니스 정책으로 인해 요청이 거부되었습니다.'가 추가됩니다.
• 요청당 최대 5개의 거부 메시지가 표시되며, 그 이상의 메시지는 생략됩니다.

테스트 실행 모드 사용 설정

테스트 실행 모드 (DRY_RUN)를 사용 설정할 수 있습니다. 테스트 실행은 정책을 시행하지 않고 평가할 수 있는 감사 전용 또는 시뮬레이션 모드입니다. 이 모드에서 정책 엔진은 제약 조건에 대해 모든 도구 호출을 평가하고 평결을 기록하지만 작업을 차단하지는 않습니다. 이렇게 하면 시행을 사용 설정하기 전에 제약 조건을 테스트하고 검증할 수 있습니다.

테스트 실행 모드를 사용 설정하려면 승인 확장 프로그램의 메타데이터에 sgpEnforcementMode: DRY_RUN를 추가합니다.

curl -X PATCH \
    "https://networkservices.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/authzExtensions/AUTHZ_EXTENSION_NAME?updateMask=metadata" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "metadata": {
        "sgpEnforcementMode": "DRY_RUN"
      }
    }'

테스트 실행 모드에서:

• 판결과 관계없이 모든 도구 호출이 허용됩니다.
• 평가 결과와 근거는 검토를 위해 로깅됩니다.
• 로그를 검토하여 차단되었을 작업을 식별하고 시행 모드로 전환하기 전에 제약 조건을 미세 조정할 수 있습니다.

일반 시행 모드로 다시 전환하려면 메타데이터에서 sgpEnforcementMode를 삭제하세요.

curl -X PATCH \
    "https://networkservices.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/authzExtensions/AUTHZ_EXTENSION_NAME?updateMask=metadata" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "metadata": {}
    }'

정책 평가 로그 보기

정책 엔진은 각 평가에 대한 구조화된 로그 항목을 프로젝트의 Cloud Logging에 작성합니다. 항목은 전체 verdict와 각 도구 또는 작업의 verdict 및 rationale가 포함된 evaluations 배열을 기록합니다.

1. 콘솔에서: 정책 페이지에서 정책을 선택합니다.
2. 세부정보 패널의 관측 가능성 섹션에서 Cloud Logging > 세부정보 보기를 클릭합니다.

3. 로그 탐색기: 쿼리 상자에 semantic-governance-policy를 입력하거나 다음 명시적 필터를 사용합니다.

   logName="projects/PROJECT_ID/logs/semantic-governance-policy"

다음은 샘플 로그 항목입니다.

{
  "jsonPayload": {
    "token_usage": 1859,
    "verdict": "ALLOW",
    "token_usage_breakdown": {"output": 43, "thinking": 0, "input": 1816, "total": 1859},
    "evaluations": [
      {
        "toolName": "process_refund",
        "verdict": "ALLOW",
        "actionName": "process_refund",
        "rationale": "The action is aligned with the user's request to process a refund and complies with the constraints regarding order ID length."
      }
    ]
  },
  "resource": {"type": "global", "labels": {"project_id": "PROJECT_NUMBER"}},
  "logName": "projects/PROJECT_ID/logs/semantic-governance-policy"
}

주요 필드:

• verdict: 전체 결정(ALLOW 또는 DENY)
• evaluations[].rationale: 정책 엔진이 각 도구 또는 작업에 대해 특정 결과를 내린 이유입니다.
• token_usage: 평가에서 사용한 모델 토큰 수입니다.

요청 추적 사용 설정

정책 엔진은 평가하는 각 요청의 trace를 프로젝트의 Cloud Trace로 내보내므로 요청별 지연 시간과 정책 시행을 검사할 수 있습니다. 이러한 trace를 수신하려면 Cloud Trace API를 사용 설정하고 Vertex AI 서비스 계정 (P4SA)에 trace를 작성할 수 있는 권한을 부여합니다.

1. Cloud Trace API를 사용 설정합니다.

   gcloud services enable cloudtrace.googleapis.com \
       --project=PROJECT_ID
   

2. Vertex AI 서비스 계정에 Cloud Trace 에이전트 역할 (roles/cloudtrace.agent)을 부여합니다. 이 역할은 trace-write 권한 (cloudtrace.traces.patch)만 부여합니다.

   export PROJECT_NUM=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
   
   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:service-${PROJECT_NUM}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
       --role="roles/cloudtrace.agent"
   

두 가지를 모두 구성한 후 에이전트를 통해 요청을 보내고 프로젝트의 Trace 탐색기에서 트레이스를 확인합니다.

정책 구성 관리

시맨틱 거버넌스 정책이 실행된 후에는 개별 정책을 삭제하거나 Agent Gateway에서 엔진을 연결 해제할 수 있습니다.

정책 삭제

전체 시맨틱 거버넌스 정책 통합에 영향을 주지 않고 개별 정책을 삭제하려면 다음 단계를 따르세요.

gcloud beta ai semantic-governance-policies delete POLICY_ID \
    --location=LOCATION \
    --project=PROJECT_ID

또는 다음 curl 명령어를 사용합니다.

curl -X DELETE \
    "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/semanticGovernancePolicies/POLICY_ID" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

정책 엔진 프로비저닝 해제

curl  -X POST "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/semanticGovernancePolicyEngine:deprovision" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{}'

gcloud beta ai semantic-governance-policy-engine deprovision \
    --location=LOCATION \
    --project=PROJECT_ID

정책 엔진을 Agent Gateway에서 연결 해제

Agent Gateway에서 정책 엔진을 연결 해제하여 도구 호출이 제약 조건에 따라 평가되지 않도록 할 수 있습니다.

시맨틱 거버넌스 정책 시행을 Agent Gateway에 바인딩하는 승인 정책을 삭제합니다.

gcloud network-security authz-policies delete AUTHZ_POLICY_NAME \
    --location=LOCATION \
    --project=PROJECT_ID

나중에 정책 엔진을 다시 연결하려면 정책 엔진을 Agent Gateway에 연결에 설명된 대로 승인 정책을 다시 만듭니다.

(선택사항) 승인 확장 프로그램 삭제

설정 중에 생성된 승인 확장 프로그램을 삭제합니다.

gcloud network-services authz-extensions delete AUTHZ_EXTENSION_NAME \
    --location=LOCATION \
    --project=PROJECT_ID

(선택사항) 고객 관리형 리소스 정리

엔진 프로비저닝 해제는 Google 관리 지원 리소스만 해체합니다. 설정 중에 자체 프로젝트에서 만든 리소스가 더 이상 필요하지 않으면 수동으로 삭제해야 합니다.

비공개 DNS 영역 삭제

gcloud dns managed-zones delete DNS_ZONE_NAME \
    --project=PROJECT_ID

서브넷 및 VPC 삭제

gcloud compute networks subnets delete SUBNET_NAME \
    --region=LOCATION \
    --project=PROJECT_ID

gcloud compute networks delete NETWORK_NAME \
    --project=PROJECT_ID

(선택사항) IAM 바인딩 삭제

Vertex AI 서비스 계정 (P4SA)에 권한을 부여한 경우 권한을 삭제할 수 있습니다.

export PROJECT_NUM=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")

gcloud projects remove-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-${PROJECT_NUM}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/compute.networkAdmin"

gcloud projects remove-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-${PROJECT_NUM}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/dns.admin"

gcloud projects remove-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-${PROJECT_NUM}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/cloudtrace.agent"

(선택사항) Cloud Trace API 사용 중지

gcloud services disable cloudtrace.googleapis.com --project=PROJECT_ID

(선택사항) Agent Platform API 사용 중지

gcloud services disable aiplatform.googleapis.com --project=PROJECT_ID

정책 시행 디버그

예상치 못한 평결을 디버그하려면 다음 단계를 따르세요.

1. 정책 평가 로그에서 평가 결과와 근거를 확인합니다.
2. 요청 추적 - 요청 추적 사용 설정을 참고하세요.
3. 테스트 실행 모드로 변경사항을 안전하게 검증하세요.
4. 배포 확인 - 엔진 상태가 ACTIVE이고 게이트웨이 바인딩이 설정됩니다.

오류 카탈로그

다음 표에는 시맨틱 거버넌스 정책을 관리할 때 발생할 수 있는 오류와 해결 단계가 나열되어 있습니다.

다음 단계

• Vertex AI gcloud CLI 명령어에 대해 자세히 알아보세요.
• 로그 탐색기에서 정책 결과를 모니터링합니다.