Esta página descreve como rotear o tráfego do Agent Runtime pelo Gateway de Agente. O Gateway de Agente é um componente central de rede e segurança do ecossistema da Gemini Enterprise Agent Platform. Ele oferece conectividade segura e controlada para todas as interações agênticas, sejam elas entre usuários e agentes, agentes e ferramentas ou entre os próprios agentes.
Antes de começar
Confira se você já sabe como implantar agentes no Agent Runtime.
Saiba mais sobre o Agent Gateway. É possível usar o Gateway de Agente no modo "Agente para qualquer lugar" (saída) para proteger e controlar todas as comunicações de saída com tráfego de saída para ferramentas, modelos, APIs e outros agentes. Use o gateway no modo "Cliente para agente" (entrada) para controlar quais clientes podem acessar seus agentes. O gateway permite escolher quais políticas do IAP e modelos do Model Armor precisam ser aplicados a essas interações.
Uma única instância do Runtime pode ser vinculada a um gateway "Agente para qualquer lugar" (saída) e a um gateway "Cliente para agente" (entrada) simultaneamente.
Limitações
- Um Gateway de Agente não pode ser vinculado a mecanismos de raciocínio do ambiente de execução criados antes de 29 de abril de 2026.
Embora um único projeto e região possam hospedar várias instâncias do Gateway de Agente "Agente para qualquer lugar" (saída) e "Cliente para agente" (entrada), todos os agentes do Agent Runtime implantados no mesmo projeto e região precisam ser vinculados às mesmas instâncias específicas do Gateway de Agente de saída e entrada.
Por exemplo, se um projeto e uma região contiverem
egress-gateway-Xeegress-gateway-Y, todos os agentes nesse projeto e região precisarão ser configurados para usar o mesmo gateway de saída. Ou seja, todos os agentes usamegress-gateway-Xou todos os agentes usamegress-gateway-Y. Não é possível configuraragent-Apara usaregress-gateway-Xeagent-Bpara usaregress-gateway-Y.Essa mesma regra de vinculação também se aplica a gateways de entrada em um projeto e região.
O serviço de detecção de ameaças do mecanismo de agentes do Security Command Center Agent Engine Threat Detection service não está disponível quando o Gateway de Agente está ativado para um agente.
No modo Cliente-Agente (entrada), o Gateway de Agente só pode controlar os métodos
queryestreamQuerydo Agent Runtime. Para proteger outros métodos não compatíveis (comoasyncQuery), é possível aplicar modelos do Model Armor diretamente do aplicativo ou agente. Consulte Limpar comandos e respostas ou este codelab sobre como criar um sistema de agentes seguro com o Model Armor.O VPC Service Controls não é compatível com o Agent Gateway.
O Gateway de Agente não é compatível com agentes do Agent Runtime que estão usando revisões. Não será possível usar recursos relacionados ao controle de versões, como a configuração de divisão de tráfego e a consulta por revisão, se um Gateway de Agente estiver anexado à configuração de um agente.
Roteie o tráfego do Agent Runtime pelo Gateway de Agente
Para rotear o tráfego do Agent Runtime pelo Gateway de Agente, siga estas etapas:
Crie um recurso do Gateway de Agente e anexe as políticas de autorização necessárias. É possível criar um gateway no modo "Agente para qualquer lugar" (saída) ou "Cliente para agente" (entrada). O agente e o gateway precisam ser criados no mesmo projeto e região. Para instruções, consulte Configurar o Gateway de Agente.
Confira se o gateway está configurado para atender às necessidades da implantação. Por exemplo, se o agente exigir acesso à LLM, configure o gateway para permitir esse acesso e evitar possíveis falhas de implantação do Agent Runtime.
Configure seu agente para rotear o tráfego pelo Gateway de Agente.
Para novos agentes
Especifique o recurso do gateway ao implantar o agente. Por exemplo, para implantar o agente no Agent Runtime, use
client.agent_engines.createpara transmitir o objetolocal_agentcom todas as configurações opcionais.Se você quiser usar recursos da plataforma mediados por gateway, como o Model Armor ou as políticas de governança semântica com esse agente, defina
agent_gateway_configeidentity_type=AGENT_IDENTITYna chamada de criação, conforme mostrado neste exemplo. Semidentity_type=AGENT_IDENTITY, oeffectiveIdentityda instância do Runtime volta para a conta de serviço padrão da Vertex AI, e as políticas de governança semântica filtram o agente silenciosamente do seletor de criação de políticas.remote_agent = client.agent_engines.create( agent=local_agent, config={ "agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME}, # "client_to_agent_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME} }, "identity_type": types.IdentityType.AGENT_IDENTITY, # Other optional configuration ... # "requirements": requirements, # "gcs_dir_name": gcs_dir_name, # https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity#opt-out-caa "env_vars": { "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False, } }, )
Substitua
AGENT_GATEWAY_TO_ANYWHERE_NAMEpelo nome do Gateway de Agente criado no modo Agente para qualquer lugar (saída).Se você criou um gateway no modo "Cliente para agente" (entrada), use o campo
client_to_agent_confige substituaAGENT_GATEWAY_CLIENT_TO_AGENT_NAMEpelo nome do Gateway de Agente criado para entrada.Para agentes atuais
Se o mecanismo foi criado originalmente semidentity_type=AGENT_IDENTITY, não é possível torná-lo qualificado para políticas de governança semântica retroativamente por meio de patches. É necessário reimplantar um novo mecanismo de raciocínio comagent_gateway_configeidentity_type=AGENT_IDENTITYdefinidos no momento da criação do agente.Agente para qualquer lugar
Use a solicitação de API REST a seguir para associar um agente atual a um gateway "Agente para qualquer lugar" para saída.
curl -X PATCH \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "spec": { "deploymentSpec": { "agentGatewayConfig": { "agentToAnywhereConfig": { "agentGateway": "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME" } } } } }' \ "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"
Substitua:
PROJECT_ID: o ID do projeto;REGION: a região em que o agente está implantado;AGENT_GATEWAY_TO_ANYWHERE_NAME: o nome do Gateway de Agente criado no modo "Agente para qualquer lugar" (saída)RESOURCE_ID: o ID do recurso do agente.
Cliente para agente
Use a solicitação de API REST a seguir para associar um agente atual a um gateway "Cliente para agente" para entrada.
curl -X PATCH \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "spec": { "deploymentSpec": { "agentGatewayConfig": { "clientToAgentConfig": { "agentGateway": "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME" } } } } }' \ "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"
Substitua:
PROJECT_ID: o ID do projeto;REGION: a região em que o agente está implantado;AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: o nome do Gateway de Agente criado no modo Cliente-para-Agente (entrada)RESOURCE_ID: o ID do recurso do agente.
Registre-se na instância do Agent Registry no mesmo projeto e região do agente e do gateway.
gcloud agent-registry services create SERVICE_NAME \ --project=PROJECT_ID \ --location=REGION \ --display-name="DISPLAY_NAME" \ --endpoint-spec-type=no-spec \ --interfaces='[{url="https://REGION-aiplatform.mtls.googleapis.com",protocolBinding="jsonrpc"}]' \ --format="value(registryResource)"Substitua:
SERVICE_NAME: o nome que você quer dar ao recurso, por exemplo,allow-aiplatform-region-eu3.PROJECT_ID: o ID do projeto.REGION: a região do registro.DISPLAY_NAME: o nome legível do endpoint.
Para mais informações, consulte Registrar um agente.
Crie uma vinculação de política do IAM de agente para registro.
gcloud iap web add-iam-policy-binding \ --resource-type=agent-registry \ --endpoint=ENDPOINT_ID \ --region=REGION \ --project=PROJECT_ID \ --member=MEMBER \ --role=roles/iap.egressor
Substitua:
ENDPOINT_ID: o ID do endpoint de serviço do agente registrado. Você recebe isso na saída da etapa anterior.MEMBER: a principal de identidade do agente a que o papel será concedido. O formato é normalmente:principal://TRUST_DOMAIN/resources/aiplatform/projects/PROJECT_ID/locations/REGION/reasoningEngines/ENGINE_ID.
Nesse momento, o tráfego do agente será direcionado pelo Gateway de Agente. No entanto, o Gateway de Agente adota uma política de negação padrão. Para ativar determinadas funções da Agent Platform, é necessário garantir que o agente possa se comunicar com os seguintes endpoints:
Se o Cloud Trace estiver ativado, o Gateway de Agente precisará permitir o tráfego para o endpoint
https://telemetry.googleapis.com/.Se as variáveis de ambiente
GOOGLE_API_USE_CLIENT_CERTIFICATEeGOOGLE_API_USE_MTLS_ENDPOINTestiverem definidas, verifique se o tráfego parahttps://telemetry.mtls.googleapis.com/também está permitido.Se o Cloud Logging estiver ativado, o Gateway de Agente precisará permitir o tráfego para o endpoint
https://logging.googleapis.com/.Se as variáveis de ambiente
GOOGLE_API_USE_CLIENT_CERTIFICATEeGOOGLE_API_USE_MTLS_ENDPOINTestiverem definidas, verifique se o tráfego parahttps://logging.mtls.googleapis.com/também está permitido.
Além disso, se os agentes estiverem chamando LLMs ou usando recursos como sessões e Memory Bank, será necessário garantir que os agentes possam se comunicar com os endpoints usados por esses serviços. Exemplo:
- Para sessões:
https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/sessions - Para o Memory Bank:
https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/memories
Por motivos de segurança, recomendamos que você registre e permita apenas os URIs específicos que o agente acessa. Como o gateway corresponde diretamente aos nomes de host, é necessário registrar todas as variantes usadas pelo SDK do agente. Por exemplo, dependendo da versão do SDK, da configuração do cliente regional ou do uso de mTLS, uma API do Google pode ser resolvida pelos seguintes nomes de host de endpoint:
https://REGION-aiplatform.googleapis.comhttps://REGION-aiplatform.mtls.googleapis.comhttps://aiplatform.REGION.rep.googleapis.com
Para saber como registrar endpoints, consulte Registrar endpoints. Também é necessário garantir que o agente tenha o papel de egressor do IAP para esses endpoints. Para instruções, consulte Criar uma política de saída de agente para endpoint.
Verifique a configuração do agente.
Console
- No Google Cloud console do, acesse a página Implantações da Agent Platform.
Clique no nome do agente implantado.
Clique em Configurações de serviço. O painel Observabilidade do agente é aberto.
Clique em Detalhes da implantação. As configurações de entrada e saída do Gateway de Agente estão disponíveis no campo Especificação de implantação.
gcloud
Use a solicitação de API REST a seguir para validar se o agente agora está associado ao gateway. Se a saída retornada for
null, isso significa que o Runtime não conseguiu se vincular ao gateway.curl -s -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID" \ | jq '.spec.deploymentSpec.agentGatewayConfig'
Substitua:
PROJECT_ID: o ID do projeto;REGION: a região em que o agente está implantado;RESOURCE_ID: o ID do recurso do agente.
- No Google Cloud console do, acesse a página Implantações da Agent Platform.
Configurar agentes de contêiner personalizado (BYOC) para o Gateway de Agente
Se você quiser rotear o tráfego de saída por um Gateway de Agente "Agente para qualquer lugar" (saída) para um agente implantado com uma imagem do contêiner personalizada (BYOC, na sigla em inglês), será necessário incorporar o certificado da autoridade certificadora raiz do gateway ao repositório de confiança da imagem do contêiner personalizada.
Como o Gateway de Agente realiza a descriptografia e a inspeção de TLS nas comunicações de saída do agente, as implantações de agentes não BYOC (baseadas em origem) injetam automaticamente o certificado da CA durante a criação da imagem. Para imagens de contêiner personalizadas, é necessário recuperar explicitamente o certificado de CA do gateway, instalá-lo no repositório de confiança da CA do sistema dentro do Dockerfile e definir as variáveis de ambiente do pacote de certificados exigidas pelos SDKs do Python, pelas bibliotecas de cliente HTTP e pelo gRPC.
Para configurar uma imagem de contêiner BYOC para a saída do Agent Gateway, siga estas etapas:
Recupere os certificados raiz do recurso do Gateway de Agente.
Exporte a string PEM do certificado raiz da CA diretamente do campo
agentGatewayCard.rootCertificatesdo recurso do Gateway de Agente:export AGW_CERT=$(gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \ --location=REGION \ --project=PROJECT_ID \ --format="value[delimiter=\\n](agentGatewayCard.rootCertificates)")
Como alternativa, é possível usar a API REST para recuperar o recurso do gateway:
curl -s -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://networkservices.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_NAME" \ | jq -r '.agentGatewayCard.rootCertificates[]'
Substitua:
AGENT_GATEWAY_NAME: o nome do Gateway de Agente de saída;REGION: a região em que o gateway está implantado;PROJECT_ID: o ID do projeto.
Atualize o
Dockerfilepara confiar no certificado de CA.Adicione o argumento de build
AGENT_GATEWAY_ROOT_CERTIFICATESaoDockerfile. Os comandos de build dividem os certificados em arquivos separados, instalam-nos usandoupdate-ca-certificatese definem variáveis de ambiente para que o OpenSSL, as bibliotecas de cliente HTTP do Python (requests,httpx) e o gRPC reconheçam a CA personalizada:# Install root certificates under root user USER root ARG AGENT_GATEWAY_ROOT_CERTIFICATES RUN if [ -n "$AGENT_GATEWAY_ROOT_CERTIFICATES" ]; then \ echo "Installing Agent Gateway root certificates..."; \ printf "%b" "$AGENT_GATEWAY_ROOT_CERTIFICATES" | awk 'BEGIN {c=0} /BEGIN CERTIFICATE/ {c++} c > 0 { print > "/usr/local/share/ca-certificates/agw-" c ".crt" }'; \ update-ca-certificates; \ fi # Configure SSL/TLS trust paths for Python HTTP libraries, OpenSSL, and gRPC ENV GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt} ENV REQUESTS_CA_BUNDLE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt} ENV SSL_CERT_FILE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt} ENV AGENT_GATEWAY_ROOT_CERT_302034098528=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt} # Switch back to application execution user USER 1000
Crie a imagem do contêiner usando o Cloud Build.
Crie um arquivo
cloudbuild.yamlpara transmitir a string do certificado raiz ao Cloud Build usando substituições:steps: - name: 'gcr.io/cloud-builders/docker' args: - 'build' - '--build-arg' - 'AGENT_GATEWAY_ROOT_CERTIFICATES=${_AGW_CERT}' - '-t' - '$_IMAGE_URI' - '.' images: - '$_IMAGE_URI'Envie o build da imagem do contêiner para o Cloud Build:
export IMAGE_URI="REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME:latest" gcloud builds submit \ --project=PROJECT_ID \ --region=REGION \ --config=cloudbuild.yaml \ --substitutions=_IMAGE_URI="$IMAGE_URI",_AGW_CERT="$AGW_CERT" \ .
Substitua
REPOSITORY_NAMEeIMAGE_NAMEpelos nomes do repositório e da imagem do Artifact Registry.Implante o agente em contêiner.
Especifique o URI da imagem do contêiner criada com a configuração do Gateway de Agente na solicitação de implantação (usando
agent_gateway_configemspec.deploymentSpecou usando chamadas de implantação do SDK).
Restringir o Agent Runtime a gateways de agente aprovados
É possível criar restrições de políticas personalizadas da organização para definir o conjunto de recursos qualificados do Gateway de Agente que podem ser usados ao implantar agentes.
Criar restrições de políticas personalizadas da organização
Este exemplo cria restrições personalizadas que permitem apenas o tráfego de e para uma lista de gateways pré-aprovados.
Agente para qualquer lugar
Para definir uma restrição personalizada para o modo "Agente para qualquer lugar" (saída), crie um arquivo chamado
constraint-agent-gateway-egress.yaml.No exemplo a seguir, o campo
conditionespecifica que a operação só é permitida se um recurso do Gateway de Agente for especificado (o campo está presente e não está vazio) e se o gateway especificado estiver na lista pré-aprovada.name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedEgressAgentGatewaysForAgentEngine resource_types: - aiplatform.googleapis.com/ReasoningEngine condition: >- has(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway) && resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway != '' && (resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway in [ 'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1', 'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2', ]) method_types: - CREATE - UPDATE action_type: ALLOW display_name: Restrict Reasoning Engine Egress to Approved Agent Gateways description: Reasoning Engines can only be bound to a pre-approved list of Agent Gateway instances. Binding to any other gateway is denied.Substitua:
- ORGANIZATION_ID: o ID da sua organização.
- AGENT_PROJECT_ID: o ID do seu projeto.
- REGION: a região em que o gateway foi criado.
- AGENT_GATEWAY_ID: o ID do gateway.
Aplique a restrição personalizada.
gcloud org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH
Substitua EGRESS_CONSTRAINT_PATH pelo caminho completo para o arquivo de restrição personalizada criado na etapa anterior.
Crie a política da organização para aplicar a restrição. Para definir a política da organização, crie um arquivo YAML de política chamado
policy-agent-gateway-egress.yaml. Neste exemplo, aplicamos essa restrição a envolvidos no projeto, mas também é possível defini-la no nível da organização ou da pasta.name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedEgressAgentGatewaysForAgentEngine spec: rules: - enforce: trueSubstitua
AGENT_PROJECT_IDpelo ID do seu projeto.Aplique a política da organização.
gcloud org-policies set-policy EGRESS_POLICY_PATH
Substitua EGRESS_POLICY_PATH pelo caminho completo para o arquivo YAML da política da organização criado na etapa anterior. A política leva até 15 minutos para entrar em vigor.
Cliente para agente
Para definir uma restrição personalizada para o modo "Cliente para agente" (entrada), crie um arquivo chamado
constraint-agent-gateway-ingress.yaml.No exemplo a seguir, o campo
conditionespecifica que a operação só é permitida se um recurso do Gateway de Agente for especificado (o campo está presente e não está vazio) e se o gateway especificado estiver na lista pré-aprovada.name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedIngressAgentGatewaysForAgentEngine resource_types: - aiplatform.googleapis.com/ReasoningEngine condition: >- has(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway) && resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway != '' && (resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway in [ 'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1', 'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2', ]) method_types: - CREATE - UPDATE action_type: ALLOW display_name: Restrict Reasoning Engine Ingress to Approved Agent Gateways description: Reasoning Engines can only be bound to a pre-approved list of Agent Gateway instances. Binding to any other gateway is denied.Substitua:
- ORGANIZATION_ID: o ID da sua organização.
- AGENT_PROJECT_ID: o ID do seu projeto.
- REGION: a região em que o gateway foi criado.
- AGENT_GATEWAY_ID: o ID do gateway.
Aplique a restrição personalizada.
gcloud org-policies set-custom-constraint INGRESS_CONSTRAINT_PATH
Substitua INGRESS_CONSTRAINT_PATH pelo caminho completo para o arquivo de restrição personalizada criado na etapa anterior.
Crie a política da organização para aplicar a restrição. Para definir a política da organização, crie um arquivo YAML de política chamado
policy-agent-gateway-ingress.yaml. Neste exemplo, aplicamos essa restrição a envolvidos no projeto, mas também é possível defini-la no nível da organização ou da pasta.name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedIngressAgentGatewaysForAgentEngine spec: rules: - enforce: trueSubstitua
AGENT_PROJECT_IDpelo ID do seu projeto.Aplique a política da organização.
gcloud org-policies set-policy INGRESS_POLICY_PATH
Substitua INGRESS_POLICY_PATH pelo caminho completo para o arquivo YAML da política da organização criado na etapa anterior. A política leva até 15 minutos para entrar em vigor.
Para mais informações sobre como usar restrições de políticas personalizadas da organização, consulte Criar restrições personalizadas.
A seguir
Codelab: controlar cargas de trabalho agênticas com a Agent Platform
Aprenda a controlar cargas de trabalho com agentes com o Gateway de Agente na Gemini Enterprise Agent Platform.
Delegar autorização para o Gateway de Agente
Aprenda a delegar a autorização do Gateway de Agente para o IAP, o Model Armor ou seu próprio serviço de autorização personalizado.
Resolver problemas do Gateway de Agente
Aprenda a resolver problemas de conectividade do Gateway de Agente.