Gerenciar o Gateway de Agente

Neste documento, descrevemos as tarefas de manutenção pós-implantação para recursos do Gateway de Agente. Se você ainda não criou um gateway, consulte Configurar o Gateway de Agente.

Antes de começar

Antes de gerenciar os recursos do Gateway de Agente, verifique os seguintes pré-requisitos:

Ver e inspecionar gateways

É possível listar os recursos do Gateway de Agente em um projeto do Google Cloud e inspecionar a configuração de um gateway, as extensões anexadas e os metadados somente de saída.

Console

  1. No console do Google Cloud , acesse a página Gateways.

    Acessar gateways

  2. Confira a lista de gateways no projeto selecionado.

  3. Clique no nome de um gateway para abrir a página de detalhes:

    • Na guia Detalhes, revise as seções Visão geral, Autorização de acesso, Segurança de IA, Extensões de serviço e Configuração da VPC.
    • Na guia Observabilidade, analise as métricas de tráfego e política do gateway. Para mais informações, consulte Monitorar o tráfego do Gateway de Agente.

gcloud

  • Liste todos os gateways em uma região específica:

    gcloud network-services agent-gateways list \
  --location=LOCATION \
  --project=PROJECT_ID

    Substitua:

    • LOCATION: a região em que os gateways são implantados, como us-central1.
    • PROJECT_ID: o ID do projeto do Google Cloud que hospeda os gateways.

  • Inspecione a configuração de um gateway específico:

    gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \
  --location=LOCATION \
  --project=PROJECT_ID

    Substitua AGENT_GATEWAY_NAME pelo nome do recurso do Gateway de Agente.

Configurações imutáveis

A maioria das configurações do Gateway de Agente, como as instâncias do Registro de Agente associadas e as políticas de segurança e governança, pode ser modificada no local, conforme descrito em Atualizar um Gateway de Agente. No entanto, algumas configurações principais são imutáveis e exigem a implantação de um gateway de substituição. Consulte a tabela a seguir antes de modificar gateways:

Configuração Mutabilidade Requisito ou restrição
Nome e região do gateway Imutável Para mudar o nome ou a região, implante um gateway de substituição.

Caminho de acesso governado

(AGENT_TO_ANYWHERE ou CLIENT_TO_AGENT)

 Imutável Configurado na criação em googleManaged.governedAccessPath. Não é possível modificar no local.

Anexo de rede do Private Service Connect

(networkAttachment)

 Imutável após a definição Depois de associar um anexo de rede a um gateway, ele não pode ser alterado ou removido.

Modelo de conectividade do agente e peering do Cloud DNS, configuração de confiança de TLS e configurações de saída de VPC associados

 Mutável condicionalmente É possível atualizar a configuração do gateway para referenciar um modelo de conectividade diferente com novas configurações, desde que o novo modelo ainda faça referência ao mesmo networkAttachment.

Substituir um gateway para mudar as configurações imutáveis

Se você precisar alterar uma configuração imutável, como o anexo de rede do PSC associado ao gateway, implante um gateway de substituição e migre as cargas de trabalho para o novo gateway:

  1. Crie o Gateway de Agente substituto e configure as políticas de autorização e do Identity and Access Management (IAM). Para instruções, consulte Configurar o Gateway de Agente.

  2. Atualize as cargas de trabalho para usar o gateway de substituição:

    • Apps do Gemini Enterprise: atualize o nome do recurso do gateway nas configurações de Segurança > Configuração do app. Consulte Rotear o tráfego do Gemini Enterprise pelo Gateway de Agente.
    • Agentes do Agent Runtime: em um único projeto e região, todos os agentes do Agent Runtime precisam se vincular ao mesmo gateway. Não é possível fazer atualizações diretas de um gateway para outro. Para migrar seus agentes:
      1. Verifique se todos os agentes vinculados encaminham 100% do tráfego para a revisão mais recente (trafficConfig.trafficSplitAlwaysLatest).
      2. Desassocie todos os agentes no projeto e na região do gateway anterior definindo spec.deploymentSpec.agentGatewayConfig como {} usando reasoningEngines.patch e aguarde a conclusão de cada operação de atualização.
      3. Chame reasoningEngines.patch em cada agente para definir spec.deploymentSpec.agentGatewayConfig como o nome do recurso do gateway de substituição. Para ver exemplos de solicitações, consulte Rotear o tráfego do Agent Runtime pelo Gateway de Agente.

  3. Depois que todas as cargas de trabalho pararem de referenciar o gateway anterior, siga as etapas em Excluir um Gateway de Agente para remover o gateway anterior.

Atualizar um Gateway de Agente

É possível atualizar determinadas configurações do Gateway de Agente diretamente no console do Google Cloud ou usando a CLI gcloud para exportar a configuração do gateway para um arquivo YAML, fazer as mudanças e reimportar o arquivo.

Atualizar o Agent Registry

É possível atualizar o Agent Registry associado no console doGoogle Cloud ou na CLI gcloud. Seu gateway precisa fazer referência ao registro regional único correspondente à região do gateway. Se o gateway estiver vinculado a um app do Gemini Enterprise, ele precisará manter um único registro correspondente ao local do app.

Console

  1. No console do Google Cloud , acesse a página Gateways.

    Acessar gateways

  2. Clique no nome do gateway que você quer atualizar.

  3. Na guia Detalhes, na seção Visão geral, clique em Editar registros.

  4. Selecione o Agent Registry regional que corresponde à região em que o gateway está implantado e clique em Salvar.

gcloud

Exporte a configuração do gateway para agent-gateway.yaml usando gcloud network-services agent-gateways export, edite registries, description ou labels (removendo campos somente de saída, como createTime, updateTime, agentGatewayCard e selfLink) e reimporte o arquivo usando gcloud network-services agent-gateways import, conforme mostrado em Atualizar o modelo de conectividade do gateway.

Atualizar o modelo de conectividade

É possível atualizar o modelo de conectividade de um recurso do Gateway de Agente usando a CLI gcloud.

gcloud

  1. Crie um novo AgentConnectivityTemplate com as configurações de conectividade atualizadas, garantindo que ele use o mesmo networkAttachment do gateway atual. Para ver a sintaxe detalhada do modelo e as instruções de configuração, consulte Configurar o Gateway de Agente com conectividade de VPC.

  2. Exporte a configuração do gateway para um arquivo YAML:

    gcloud network-services agent-gateways export AGENT_GATEWAY_NAME \
 --destination="agent-gateway.yaml" \
 --location=LOCATION \
 --project=PROJECT_ID

    Substitua:

    • AGENT_GATEWAY_NAME: o nome do gateway a ser atualizado.
    • LOCATION: a região em que o gateway está implantado.
    • PROJECT_ID: o ID do projeto em que o gateway está implantado.

  3. No arquivo agent-gateway.yaml exportado, mantenha os campos protocols, registries, description e labels intactos, remova os campos somente de saída (createTime, updateTime, agentGatewayCard, selfLink) e atualize agentConnectivityTemplate para referenciar o novo modelo:

    name: projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - //agentregistry.googleapis.com/projects/PROJECT_NUMBER/locations/LOCATION
agentConnectivityTemplate: projects/PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/NEW_TEMPLATE_NAME

    Substitua:

    • PROJECT_NUMBER: o número do projeto em que o gateway é implantado (agentConnectivityTemplate requer o número do projeto, não o ID do projeto).
    • LOCATION: a região do gateway.
    • AGENT_GATEWAY_NAME: o nome do gateway.
    • NEW_TEMPLATE_NAME: o nome do modelo de conectividade de substituição.

  4. Importe novamente o arquivo YAML atualizado para aplicar as mudanças:

    gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \
 --source="agent-gateway.yaml" \
 --location=LOCATION \
 --project=PROJECT_ID

  5. Opcional: exclua o modelo de conectividade anterior após a conclusão da atualização do gateway:

    gcloud network-services agent-connectivity-templates delete OLD_TEMPLATE_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

Modificar as configurações do IAP ou os modelos do Model Armor

É possível modificar as configurações de aplicação do IAP e os modelos do Model Armor atualizando as extensões de autorização anexadas ao gateway.

Console

  1. No console do Google Cloud , acesse a página Gateways.

    Acessar gateways

  2. Clique no nome do gateway que você quer atualizar.

  3. Na guia Detalhes, atualize as extensões de segurança anexadas:

    • Mudar o modo restrito do IAP: na seção Autorização de acesso, ao lado de Autorização de acesso, clique em Editar autorização de acesso. Selecione Somente auditoria (modo de teste) ou Aplicar políticas e clique em Salvar.

    • Mudar os modelos do Model Armor: na seção Segurança de IA, clique em Editar modelo de solicitação ao lado de Modelo para solicitações ou em Editar modelo de resposta ao lado de Modelo para respostas. Selecione o modelo de substituição e clique em Salvar.

gcloud

  1. Liste as extensões de autorização na região do gateway para identificar o nome da extensão:

    gcloud service-extensions authz-extensions list \
 --location=LOCATION \
 --project=PROJECT_ID

    Substitua LOCATION pela região do gateway e PROJECT_ID pelo ID do projeto.

  2. Inspecione a configuração atual da extensão:

    gcloud service-extensions authz-extensions describe AUTHZ_EXTENSION_NAME \
 --location=LOCATION \
 --project=PROJECT_ID \
 --format=yaml

    Substitua AUTHZ_EXTENSION_NAME pelo nome do recurso AuthzExtension do IAP ou do Model Armor.

  3. Salve a especificação de extensão atualizada em authz-extension.yaml, omitindo campos somente de saída, como createTime e updateTime:

    • Para uma extensão do IAP: inclua iamEnforcementMode: "DRY_RUN" para o modo somente auditoria ou remova iamEnforcementMode para aplicar políticas:

      name: AUTHZ_EXTENSION_NAME
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V2"
  iamEnforcementMode: "DRY_RUN" # Omit this line to enforce policies

    • Para uma extensão do Model Armor: atualize request_template_id e response_template_id em metadata.model_armor_settings:

      name: AUTHZ_EXTENSION_NAME
service: modelarmor.LOCATION.rep.googleapis.com
failOpen: false
timeout: 1s
metadata:
  model_armor_settings: '[
    {
      "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID",
      "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID"
    }
  ]'

      Substitua:

      • AUTHZ_EXTENSION_NAME: o nome do recurso AuthzExtension do Model Armor.
      • LOCATION: a região do gateway.
      • MODEL_ARMOR_PROJECT_ID: o ID do projeto que hospeda seus modelos do Model Armor.
      • REQUEST_TEMPLATE_ID e RESPONSE_TEMPLATE_ID: os IDs dos modelos de solicitação e resposta.

      Verifique se a conta de serviço do gateway (agentGatewayCard.serviceExtensionsServiceAccount) tem roles/modelarmor.user em qualquer projeto de modelo recém-referenciado, bem como roles/modelarmor.calloutUser e roles/serviceusage.serviceUsageConsumer no projeto do gateway (consulte Autorização de delegação).

  4. Importe o arquivo YAML atualizado da extensão:

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

Para anexar novas políticas de autorização ou modificar regras de correspondência de tráfego em um AuthzPolicy, consulte Delegar autorização.

Desassociar cargas de trabalho de um Gateway de Agente

Antes de excluir um Gateway de Agente, é necessário desassociar todos os apps do Gemini Enterprise e agentes do Agent Runtime que fazem referência ao gateway.

Desassociar um app do Gemini Enterprise

É possível desvincular um Gateway de Agente de um app do Gemini Enterprise no console do Google Cloud :

  1. No console Google Cloud , acesse a página Gemini Enterprise.

    Acessar o Gemini Enterprise

  2. Clique no nome do app associado ao gateway.

  3. Clique em Segurança.

  4. Na guia Configuração, em Configuração do gateway de agente, limpe o campo Nome do recurso do gateway de agente.

  5. Clique em Salvar.

Ao desassociar um Gateway de Agente, o tráfego de saída do app deixa de ser roteado pelo gateway. Os agentes importados e os servidores do Protocolo de Contexto de Modelo (MCP) permanecem registrados no Registro de Agente, mas o app não pode acessá-los até que você vincule um gateway novamente. O novo gateway precisa fazer referência ao mesmo registro de agente.

Desassociar um agente do Agent Runtime

O console do Google Cloud e a CLI gcloud não são compatíveis com a modificação de vinculações de gateway do Agent Runtime. Para desassociar um Gateway de Agente de um agente do Agent Runtime implantado sem interromper o funcionamento do agente, chame o método da API REST reasoningEngines.patch para limpar spec.deploymentSpec.agentGatewayConfig:

  1. Verifique se o agente encaminha todo o tráfego para a revisão mais recente (trafficConfig.trafficSplitAlwaysLatest definido como true ou nenhuma divisão manual de trafficConfig configurada). A limpeza ou alteração de uma vinculação de gateway falhará se uma divisão de tráfego de revisão manual estiver ativa e arquivar irreversivelmente todas as revisões anteriores. Para mais detalhes, consulte Gateway de Agente e revisões.

  2. Envie uma solicitação PATCH ao mecanismo de raciocínio com updateMask=spec.deploymentSpec.agentGatewayConfig e um objeto agentGatewayConfig vazio ({}):

    curl -X PATCH \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 -d '{
   "spec": {
     "deploymentSpec": {
       "agentGatewayConfig": {}
     }
   }
 }' \
 "https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

    Substitua:

    • REGION: a região em que o agente é implantado.
    • PROJECT_ID: o ID do projeto em que o agente está implantado.
    • RESOURCE_ID: o ID do recurso do agente.

Excluir um Gateway de Agente

O Gateway de Agente aplica um rastreamento de referência rigoroso para evitar políticas de segurança órfãs e caminhos de tráfego de agentes corrompidos. A exclusão de um gateway falha, e o botão Excluir no console do Google Cloud permanece indisponível se alguma das seguintes condições se aplicar:

  • Um ou mais agentes do Agent Runtime ou apps do Gemini Enterprise ainda fazem referência ao gateway.
  • Qualquer AuthzPolicy (para IAP, Model Armor ou um provedor personalizado) ou TelemetryPolicy ainda segmenta o gateway.
  • Uma operação de atualização da configuração da VPC ainda está em execução no gateway.

Siga as etapas abaixo para excluir um Gateway de Agente e limpar os recursos associados:

Console

  1. Verifique se nenhum app do Gemini Enterprise ou agente do Agent Runtime faz referência ao gateway. Siga as instruções em Desassociar cargas de trabalho de um Gateway de Agente.

  2. No console do Google Cloud , acesse a página Gateways.

    Acessar gateways

  3. Clique no nome do gateway que você quer excluir.

  4. Na guia Detalhes, remova todas as associações de política que segmentam o gateway:

    • Se a seção Autorização de acesso aparecer, clique em Remover e confirme a exclusão. Essa ação exclui o AuthzPolicy do IAP e o AuthzExtension dele.
    • Se a seção Segurança de IA aparecer, clique em Remover e confirme a exclusão. Essa ação exclui o Model Armor AuthzPolicy e o AuthzExtension dele.
    • Verifique a tabela Extensões de serviço. Se algum recurso AuthzPolicy personalizado permanecer anexado, use a guia gcloud neste procedimento para excluí-los antes de continuar.

  5. Depois que todas as associações de política forem removidas e nenhuma atualização de VPC estiver em andamento, clique em Excluir e confirme a exclusão.

  6. Confirme se o gateway não aparece mais na lista Gateways do projeto.

  7. Opcional: limpe os recursos de conectividade não utilizados se nenhum outro gateway os usar. Use a guia gcloud para excluir o AgentConnectivityTemplate e excluir o anexo de rede.

gcloud

  1. Verifique se nenhum app do Gemini Enterprise ou agente do Agent Runtime faz referência ao gateway. Siga as instruções em Desassociar cargas de trabalho de um Gateway de Agente.

  2. Remova as políticas e extensões de autorização:

    1. Liste as políticas de autorização na região do gateway para encontrar políticas em que o campo target.resources faça referência ao gateway e anote qualquer authzExtensions referenciado:

      gcloud network-security authz-policies list \
  --location=LOCATION \
  --project=PROJECT_ID \
  --format="yaml(name,target.resources,customProvider.authzExtension.resources)"

      Substitua LOCATION pela região do gateway e PROJECT_ID pelo ID do projeto.

    2. Exclua cada AuthzPolicy que segmenta o gateway:

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

      Substitua AUTHZ_POLICY_NAME pelo ID de cada política de autorização que segmenta o gateway (por exemplo, AGENT_GATEWAY_NAME-iap-authzpolicy ou AGENT_GATEWAY_NAME-aisecurity-authzpolicy para políticas criadas pelo console).

    3. Opcional: depois de excluir os recursos AuthzPolicy de referência, exclua todos os recursos AuthzExtension que não são usados por outras políticas:

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

      Substitua AUTHZ_EXTENSION_NAME pelo ID da extensão de autorização não utilizada.

  3. Exclua o Gateway de Agente:

    gcloud network-services agent-gateways delete AGENT_GATEWAY_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

    Substitua AGENT_GATEWAY_NAME pelo nome do gateway a ser excluído.

  4. Confirme se o gateway não aparece mais na lista de gateways regionais:

    gcloud network-services agent-gateways list \
 --location=LOCATION \
 --project=PROJECT_ID

  5. Opcional: não é possível excluir um AgentConnectivityTemplate enquanto um Gateway de Agente o referencia. Depois de excluir o gateway, exclua todos os modelos de conectividade não utilizados:

    gcloud network-services agent-connectivity-templates delete CONNECTIVITY_TEMPLATE_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

    Substitua CONNECTIVITY_TEMPLATE_NAME pelo nome do modelo de conectividade não utilizado. Se você não precisar mais do anexo de rede subjacente do Private Service Connect, das zonas privadas do Cloud DNS ou dos recursos TrustConfig do Gerenciador de Certificados, consulte Excluir anexos de rede.

A seguir

Guia

Saiba como delegar a autorização do Gateway de Agente ao IAP, ao Model Armor ou ao seu próprio serviço de autorização personalizado.

Guia

Saiba como monitorar o Gateway de Agente.

Guia

Saiba como configurar um Gateway de Agente.

Solução de problemas

Saiba como resolver problemas de conectividade do Gateway de Agente.