Configurar políticas de governança semântica

Configurar as políticas de governança semântica e o Policy Engine

Esta seção aborda a transição da prontidão da infraestrutura para a criação de políticas.

Pré-requisitos

Antes de configurar as políticas de governança semântica, siga estas etapas.

Ativar APIs obrigatórias

Antes de começar, ative as APIs necessárias para a política de governança semântica e os componentes de rede dela:

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

Conceder permissões do IAM à conta de serviço da Vertex AI (somente vinculação gerenciada pelo Google)

Se você usar a opção de vinculação gerenciada pelo Google durante o provisionamento, conceda à conta de serviço da Vertex AI (P4SA) os papéis necessários para criar o endpoint do Private Service Connect (PSC) (roles/compute.networkAdmin) e o conjunto de registros DNS (roles/dns.admin) no seu projeto. Se você usar a opção Vinculação autogerenciada, pule esta etapa, porque você cria esses recursos de rede por conta própria.

Crie a identidade de serviço (idempotente) e conceda os papéis:

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"

Os comandos de remoção correspondentes estão em Remover as vinculações do IAM na seção de limpeza.

Requisitos de qualificação do agente

Para aparecer no seletor de agentes de uma política de governança semântica no console doCloud de Confiance , o mecanismo de raciocínio de um agente precisa ter sido implantado com identity_type=AGENT_IDENTITY e agent_gateway_config definidos ao mesmo tempo. Se algum deles estiver ausente, o console do Cloud de Confiance vai filtrar o agente do seletor. Em vez disso, a API e o gcloud retornam um erro explícito.

Para implantar um agente que atenda a esses requisitos, siga as instruções em Rotear o tráfego do Agent Runtime pelo Gateway de Agente. Os dois campos são imutáveis em um mecanismo de raciocínio atual. Portanto, um agente implantado sem eles precisa ser reimplantado. A aplicação de patches não vai funcionar.

Para verificar se um agente atual está qualificado, confirme se o spec.effectiveIdentity do mecanismo de raciocínio dele começa com 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"

Locais suportados

O mecanismo de políticas de governança semântica e as políticas de governança semântica são compatíveis com os seguintes locais regionais:

Provisionamento e ativação

Ative o mecanismo de política de governança semântica. Isso provisiona o ambiente de execução necessário. O provisionamento geralmente leva de 2 a 3 minutos para ser concluído. No entanto, quando a demanda é alta ou o pool de aquecimento está sendo reabastecido, o provisionamento pode levar até 20 minutos. Escolha uma das seguintes opções de provisionamento:

• Vinculação gerenciada pelo Google:o Google cria os recursos de rede no seu projeto do Cloud de Confiance by S3NS e gerencia o ciclo de vida deles automaticamente.
• Vinculação autogerenciada:você cria e gerencia os recursos de rede necessários (network, subnetwork e dnsZoneName) diretamente no seu projeto do Cloud de Confiance by S3NS .

Depois de concluir o provisionamento, conecte o Policy Engine ao Gateway de Agente.

Vinculação gerenciada pelo 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"

Substitua:

• GATEWAY_NAME por um nome de gateway exclusivo.
• DNS_NAME pelo nome da zona de DNS particular que será usada.
• PROJECT_ID pelo ID do projeto do Cloud de Confiance by S3NS (projects/PROJECT_ID/global/networks/default). Se você usar uma rede e uma sub-rede personalizadas, substitua os caminhos de recursos completos de network e subnetwork de acordo.

Recuperar o nome do host DNS gerado automaticamente

Quando você provisiona o mecanismo com a vinculação gerenciada pelo Google, o Google cria automaticamente um endpoint do Private Service Connect (PSC) e registra um registro A de DNS na sua zona de DNS particular. O FQDN desse registro serve como o SGP_DNS_HOSTNAME e é preenchido no campo somente de saída dnsRecord da configuração do gateway.

Para recuperar o nome do host DNS gerado automaticamente:

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)"

Na resposta, localize o campo dnsRecord em gatewayConfigs.GATEWAY_NAME.dnsRecord. Salve esse FQDN, que será necessário como o SGP_DNS_HOSTNAME quando você conectar o Policy Engine ao Gateway de Agente.

Vinculação autogerenciada

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

Esse comando retorna uma operação de longa duração. É possível pesquisar o status da operação substituindo OPERATION pelo valor name da resposta:

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

Como alternativa, verifique o status geral do mecanismo até que o campo state retorne 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"

Configurar a rede (somente autogerenciada)

Depois que o Policy Engine for provisionado, configure os componentes de rede necessários para que o Gateway de Agente se comunique com o Policy Engine.

Enquanto o Google cria automaticamente o endpoint do PSC em um projeto de locatário gerenciado pelo Google para o caminho gerenciado pelo Google, para o caminho autogerenciado, é necessário criar e gerenciar manualmente o endpoint do PSC no seu próprio projeto do Cloud de Confiance by S3NS .

1. Provisionar rede e sub-rede VPC

Nesta etapa, você vai criar uma rede VPC, uma sub-rede e uma sub-rede somente proxy para o tráfego de agentes. Os intervalos de IP mostrados (10.11.12.0/24 e 10.11.13.0/24) são exemplos. É possível usar qualquer intervalo particular RFC 1918 que se ajuste ao design da sua rede.

1. Crie a rede VPC:

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

   Substitua NETWORK_NAME pelo nome da rede VPC (por exemplo, agent-network).

2. Crie a sub-rede:

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

   Substitua SUBNET_NAME pelo nome da sub-rede (por exemplo, agent-subnet).

3. Crie a sub-rede somente proxy (necessária para balanceadores de carga gerenciados):

   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
   

   Substitua PROXY_SUBNET_NAME pelo nome da sub-rede somente proxy (por exemplo, agent-proxy-subnet).

2. Provisionar zona de DNS particular

Crie uma zona de DNS particular para permitir que o Gateway de Agente resolva o nome do host do Policy Engine:

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: o nome da zona de DNS (por exemplo, my-private-zone).
• internal.example.com.: o nome DNS da zona, incluindo o ponto final.

3. Criar anexo de rede

Crie um anexo de rede para permitir que o Gateway de Agente se conecte a recursos na sua VPC. A preferência de conexão precisa ser definida como 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: o nome do anexo de rede (por exemplo, sgp-nw-attachment).
• SUBNET_NAME: a sub-rede que você criou na etapa 1.

4. Criar IP estático, endpoint do PSC e registro DNS

Reserve um endereço IP estático, crie um endpoint do Private Service Connect (PSC) que aponte para o anexo de serviço do Policy Engine e crie um registro DNS para torná-lo acessível.

# 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

Substitua:

• STATIC_IP_NAME: o nome do endereço IP reservado (por exemplo, sgp-psc-ip).
• PSC_ENDPOINT_NAME: o nome do endpoint do PSC (por exemplo, sgp-psc-endpoint).
• PSC_SERVICE_ATTACHMENT: o valor de pscServiceAttachment salvo da resposta de provisionamento.
• SGP_DNS_HOSTNAME: um nome do host na zona de DNS particular, no formato LOCATION.DNS_ZONE_SUFFIX, em que DNS_ZONE_SUFFIX é o nome de DNS especificado ao criar a zona de DNS particular. Por exemplo, se o local for us-west1 e o sufixo da zona de DNS for internal.example.com, use us-west1.internal.example.com.

5. Configurar a conectividade da VPC no Gateway de Agente

Depois de criar os recursos de rede, registre o anexo de rede e o peering de DNS no Gateway de Agente para que ele possa acessar o mecanismo de políticas pela rede privada.

Para instruções detalhadas, consulte Configurar a conectividade da VPC no guia de configuração do Gateway de Agente. No mínimo, você precisa:

• Registre o anexo de rede criado na etapa 3 com a configuração de saída do Gateway de Agente.
• Registre o peering de DNS para que o gateway possa resolver o nome de host de DNS particular criado na etapa 4.

Conectar o Policy Engine ao Gateway de Agente

Depois que a rede for configurada, crie uma extensão de autorização e uma política de autorização para que o Gateway de Agente possa encaminhar o tráfego ao Policy Engine para avaliação.

1. Criar a extensão de autorização: crie uma extensão de autorização que aponte para o nome do host DNS do Policy Engine. Use o mesmo SGP_DNS_HOSTNAME para o qual você criou um registro DNS em Configurar a rede (etapa 4). Esse é o mecanismo pelo qual o Gateway de Agente envia tráfego ao mecanismo de políticas para avaliação.

   gcloud

   Defina a configuração da extensão em um arquivo YAML (authz-ext.yaml) e importe-o:

   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"
       }'
   

   Substitua SGP_DNS_HOSTNAME pelo nome do host DNS para o qual você criou um registro A em Como configurar a rede (etapa 4).

   Esse comando retorna uma operação de longa duração. Aguarde a operação terminar e depois continue.

2. Criar a política de autorização: crie uma política de autorização que vincule a extensão ao Gateway de Agente. Isso instrui o Gateway de Agente a enviar tráfego pelo Policy Engine para avaliação.

   gcloud

   Defina a configuração da política de autorização em um arquivo YAML (authz-policy.yaml) e importe-o:

   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"]
           }
         }
       }'
   

   Esse comando retorna uma operação de longa duração. Aguarde a operação terminar e depois continue.

Criar uma política

Depois que o mecanismo de políticas estiver ativo, você poderá definir as proteções técnicas e comportamentais para seus agentes.

1. Defina o escopo: determine se a política se aplica a todas as ações realizadas por um agente ou se é voltada para uma ferramenta específica.
2. Crie as restrições: forneça suas regras de negócios em inglês simples.

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

Mensagens de negação com várias políticas

Quando uma única solicitação aciona negações de várias políticas, o mecanismo de políticas combina as mensagens de negação configuradas nessas políticas antes de retornar a resposta ao usuário. O comportamento a seguir se aplica:

• As mensagens de negação de cada política com um veredito de negação são mostradas juntas, separadas por linhas em branco.
• As mensagens duplicadas são mostradas uma vez.
• Se algumas políticas de disparo tiverem uma mensagem de negação configurada e outras não, uma linha genérica "Esta solicitação foi negada devido a outra política comercial" será adicionada para cobrir as políticas sem uma.
• No máximo, cinco mensagens de negação são mostradas por solicitação. As outras são omitidas.

Como ativar o modo de teste

É possível ativar o modo de teste (DRY_RUN), que é um modo de simulação ou somente auditoria para avaliar políticas sem aplicá-las. Nesse modo, o Policy Engine avalia todas as chamadas de ferramentas em relação às suas restrições e registra os vereditos, mas nunca bloqueia ações. Isso permite testar e validar as restrições antes de ativar a aplicação.

Para ativar o modo de teste, adicione sgpEnforcementMode: DRY_RUN aos metadados da extensão de autorização:

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"
      }
    }'

No modo de teste:

• Todas as chamadas de ferramenta são permitidas, independentemente do veredito.
• As decisões e justificativas são registradas para análise.
• É possível analisar os registros para identificar quais ações teriam sido bloqueadas e refinar as restrições antes de mudar para o modo restrito.

Para voltar ao modo restrito normal, remova sgpEnforcementMode dos metadados:

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": {}
    }'

Ver registros de avaliação de políticas

O Policy Engine grava uma entrada de registro estruturada para cada avaliação no Cloud Logging no seu projeto. A entrada registra um verdict geral e uma matriz evaluations com um verdict e um rationale para cada ferramenta ou ação.

1. No console:na página Políticas, selecione uma política.
2. No painel Detalhes, na seção Observabilidade, clique em Cloud Logging > Ver detalhes.

3. Na Análise de registros:digite semantic-governance-policy na caixa de consulta ou use o seguinte filtro explícito:

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

Confira a seguir um exemplo de entrada de registro:

{
  "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"
}

Campos-chave:

• verdict: decisão geral, ALLOW ou DENY.
• evaluations[].rationale: a justificativa para o Policy Engine ter chegado a um determinado veredito para cada ferramenta ou ação.
• token_usage: o número de tokens de modelo que a avaliação consumiu.

Ativar o rastreamento de solicitações

O mecanismo de políticas exporta um trace para cada solicitação que ele avalia para o Cloud Trace no seu projeto, para que você possa inspecionar a latência por solicitação e a aplicação de políticas. Para receber esses traces, ative a API Cloud Trace e conceda à conta de serviço da Vertex AI (P4SA) permissão para gravar traces.

1. Ative a API Cloud Trace:

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

2. Conceda o papel de agente do Cloud Trace (roles/cloudtrace.agent) à conta de serviço da Vertex AI. Esse papel concede apenas a permissão de gravação de trace (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"
   

Depois que ambos estiverem configurados, envie uma solicitação pelo agente e confira os traces no Explorador de traces do seu projeto.

Gerenciar configuração de política

Depois que a política de governança semântica estiver em execução, você poderá excluir políticas individuais ou desconectar o mecanismo do Gateway de Agente.

Excluir uma política

Para remover uma política individual sem afetar a integração geral da política de governança semântica:

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

Como alternativa, use o seguinte comando 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)"

Desprovisionar um mecanismo de políticas

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

Desconectar o Policy Engine do Gateway de Agente

É possível desconectar o mecanismo de políticas do Gateway de Agente para interromper a avaliação das chamadas de ferramentas em relação às restrições.

Exclua a política de autorização que vincula a aplicação da política de governança semântica ao Gateway de Agente:

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

Para reconectar o mecanismo de políticas mais tarde, recrie a política de autorização conforme descrito em Conectar o mecanismo de políticas ao Gateway de Agente.

(Opcional) Excluir a extensão de autorização

Exclua a extensão de autorização criada durante a configuração.

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

(Opcional) Limpar recursos gerenciados pelo cliente

O desprovisionamento do mecanismo apenas destrói os recursos de apoio gerenciados pelo Google. Você precisa excluir manualmente os recursos criados no seu projeto durante a configuração se eles não forem mais necessários.

Remover a zona de DNS particular

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

Remover a sub-rede e a VPC

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

gcloud compute networks delete NETWORK_NAME \
    --project=PROJECT_ID

(Opcional) Remover as vinculações do IAM

Se você concedeu permissões à conta de serviço da Vertex AI (P4SA), é possível removê-las:

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"

(Opcional) Desativar a API Cloud Trace

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

(Opcional) Desativar a API Agent Platform

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

Depurar a aplicação de políticas

Para depurar um veredito inesperado:

1. Verifique o veredito e a justificativa nos registros de avaliação da política.
2. Rastreie a solicitação: consulte Ativar o rastreamento de solicitações.
3. Valide as mudanças com segurança usando o modo de teste.
4. Confirme a implantação: o estado do mecanismo é ACTIVE e a vinculação do gateway foi estabelecida.

Catálogo de erros

A tabela a seguir lista os erros que podem ocorrer ao gerenciar políticas de governança semântica, além das etapas para resolvê-los:

A seguir

• Saiba mais sobre os comandos da CLI gcloud da Vertex AI.
• Monitore as decisões de política na Análise de registros.