Acessar o Apigee de forma particular na Gemini Enterprise Agent Platform

Esta página se aplica à Apigee, mas não à Apigee híbrida.

Confira a documentação da Apigee Edge.

Neste documento, descrevemos como configurar a conectividade privada de um agente implantado na plataforma de agentes do Gemini Enterprise no tempo de execução do agente para APIs e ferramentas do Model Context Protocol (MCP) publicadas na Apigee, usando o Private Service Connect. Com esse padrão, o tráfego do agente para o Apigee permanece totalmente privado e não passa pela Internet pública.

Informações sobre preços:para saber mais sobre como o Private Service Connect é medido e faturado, consulte Private Service Connect na página de preços da nuvem privada virtual. Para informações sobre preços do Agent Platform, consulte Preços do Agent Platform.

Visão geral

O Agent Runtime implanta seu agente em uma rede segura gerenciada pelo Google sem acesso à sua rede de nuvem privada virtual (VPC). Da mesma forma, a Apigee é executada em uma rede segura gerenciada pelo Google. Quando você quer que as chamadas de um agente para um modelo de linguagem grande (LLM) ou para ferramentas do MCP expostas pela Apigee sejam feitas de forma privada, é necessário uma maneira de conectar essas duas redes gerenciadas pelo Google por uma rede VPC que você controla.

Este documento descreve o seguinte padrão para essa ponte:

• O Agent Runtime provisiona uma interface do Private Service Connect (interface do PSC) que se conecta a um anexo de rede em uma sub-rede da sua VPC de consumidor. O tráfego de saída do seu agente sai para essa VPC.
• Na mesma VPC do consumidor, crie um endpoint do Private Service Connect que tenha como destino o anexo de serviço que sua instância da Apigee expõe.
• Crie uma zona particular do Cloud DNS na VPC do consumidor que resolve o nome do host do grupo de ambiente do Apigee para o endereço IP do endpoint do Private Service Connect.
• O Agent Runtime usa o peering de DNS para resolver esse nome de host no ambiente do Agent Runtime usando a zona privada na VPC do consumidor.

Com essa configuração, quando o agente chama https://APIGEE_HOSTNAME/..., a solicitação é resolvida para o IP do endpoint do Private Service Connect na sua VPC, encaminhada pelo anexo de serviço para sua instância do Apigee e processada pelo proxy de API que corresponde ao caminho da solicitação.

Observação:o padrão descrito neste documento usa um endpoint do Private Service Connect diretamente. O TLS é encerrado na entrada da instância do Apigee, que apresenta um certificado autoassinado aos clientes que se conectam pelo endpoint do Private Service Connect. Se o cliente exigir um certificado confiável publicamente no caminho particular, use um balanceador de carga de aplicativo interno com um grupo de endpoints da rede (NEG) do Private Service Connect na frente do serviço anexado. Consulte Rede de saída com o Private Service Connect para esse padrão.

Antes de começar

Este documento usa os seguintes marcadores de posição nos comandos. Substitua-os por valores do seu ambiente.

• APIGEE_PROJECT_ID: o ID do projeto Google Cloud que contém sua organização da Apigee.
• SERVICE_PROJECT_ID: o ID do projeto Google Cloud em que você implanta seu agente no Agent Runtime. Ele pode ser o mesmo que APIGEE_PROJECT_ID ou um projeto diferente, dependendo de como você organiza seus recursos do Google Cloud.
• SERVICE_PROJECT_NUMBER: o número numérico do projeto para SERVICE_PROJECT_ID. É possível recuperá-lo com gcloud projects describe SERVICE_PROJECT_ID --format="value(projectNumber)".
• HOST_PROJECT_ID: o ID do projeto Google Cloud que contém a rede VPC, a sub-rede e a zona particular do Cloud DNS do consumidor. Isso é o mesmo que SERVICE_PROJECT_ID, a menos que você esteja usando a VPC compartilhada. Nesse caso, esse é o projeto host ao qual o projeto de serviço é anexado.
• REGION: a região da sua instância da Apigee (por exemplo, us-west1).
• VPC_NAME: o nome da rede VPC do consumidor em HOST_PROJECT_ID.
• SUBNET_NAME: o nome de uma sub-rede em VPC_NAME localizada em REGION.
• APIGEE_HOSTNAME: o nome do host configurado no grupo de ambiente da Apigee (por exemplo, api.internal.example.com).
• BASE_PATH: o caminho de base do proxy de API implantado na Apigee (por exemplo, /mcp ou /orders).
• PARENT_DNS_NAME: o domínio DNS principal de APIGEE_HOSTNAME que você quer veicular na zona privada (por exemplo, internal.example.com.). O valor precisa terminar com um ponto.
• APIGEE_INSTANCE_NAME: o nome da sua instância da Apigee em REGION.

Observação sobre a topologia do projeto:APIGEE_PROJECT_ID, SERVICE_PROJECT_ID e HOST_PROJECT_ID são independentes. Eles podem ser todos iguais, todos diferentes ou qualquer combinação que se ajuste à forma como você organiza seus recursos do Google Cloud.

• Se você usar a VPC compartilhada na rede do consumidor, HOST_PROJECT_ID será o projeto host e SERVICE_PROJECT_ID será um projeto de serviço anexado a ele. Caso contrário, HOST_PROJECT_ID é igual a SERVICE_PROJECT_ID.
• Para detalhes sobre qual projeto é proprietário do anexo de rede e os papéis do IAM correspondentes em uma implantação de VPC compartilhada, consulte Usar a interface do Private Service Connect com a VPC compartilhada na documentação da Agent Platform.

Você precisará do seguinte:

• Um ou mais projetos do Google Cloud (conforme descrito na observação anterior) com o faturamento ativado.
• Uma organização da Apigee em APIGEE_PROJECT_ID com pelo menos uma instância. Este documento cria todos os recursos de rede do consumidor (anexo de rede, endpoint do Private Service Connect, implantação do Agent Runtime) na mesma região da sua instância da Apigee, que é a configuração mais simples.
• Um grupo de ambiente cujos ambientes são implantados nessa instância da Apigee e que inclui o nome do host que você quer que o agente chame. Este documento se refere a esse nome de host como APIGEE_HOSTNAME.
• Pelo menos um proxy de API implantado em um ambiente nesse grupo de ambientes. Todos os proxies que você quer que o agente chame precisam estar acessíveis em https://APIGEE_HOSTNAME/BASE_PATH.
• Uma rede VPC e uma sub-rede em HOST_PROJECT_ID, na mesma região da instância do Apigee. Este documento se refere a eles como VPC_NAME e SUBNET_NAME. O Agent Runtime exige uma sub-rede mínima de /28 e impõe outras restrições de intervalo. Para mais detalhes, consulte Requisitos de intervalo de IP da sub-rede na documentação do Agent Platform.
• As seguintes APIs ativadas no projeto adequado:
  • Apigee (apigee.googleapis.com) em APIGEE_PROJECT_ID.
  • Compute Engine (compute.googleapis.com) e Cloud DNS (dns.googleapis.com) em HOST_PROJECT_ID.
  • Agent Platform (aiplatform.googleapis.com) em SERVICE_PROJECT_ID.
• Permissões suficientes do IAM para criar zonas e registros do Cloud DNS, endereços do Compute Engine, anexos de rede e regras de encaminhamento do Private Service Connect em HOST_PROJECT_ID, além de atualizar a configuração da instância e do grupo de ambiente do Apigee em APIGEE_PROJECT_ID. Para detalhes sobre os papéis necessários, consulte Papéis da Apigee, Controle de acesso do Cloud DNS e Papéis do IAM do Compute Engine.

Arquitetura

As etapas a seguir descrevem o fluxo de tráfego entre um agente implantado no Agent Runtime e um proxy de API hospedado no Apigee, usando um endpoint do Private Service Connect em uma VPC de consumidor como a ponte.

1. O agente, executado no Agent Runtime, faz uma solicitação HTTPS para APIGEE_HOSTNAME.
2. O peering de DNS configurado na interface PSC do Agent Runtime encaminha a pesquisa para a zona particular do Cloud DNS na sua VPC de consumidor, que retorna o endereço IP do endpoint do Private Service Connect.
3. A solicitação do agente sai pela interface do PSC para sua VPC de consumidor e chega ao endpoint do Private Service Connect nesse endereço IP.
4. O endpoint do Private Service Connect encaminha a solicitação pela conexão de serviço ao anexo de serviço da instância do Apigee.
5. A instância do Apigee encerra o TLS, corresponde ao nome do host da solicitação ao grupo de ambiente e roteia para o proxy de API correto.

Etapa 1: configurar a rede na VPC do consumidor

Nesta seção, configuramos recursos em dois projetos. Cada comando inclui uma flag --project explícita para que você possa executar os comandos de qualquer configuração ativa do gcloud:

• Os recursos do Cloud DNS (zona e registro particulares) são criados em HOST_PROJECT_ID porque a zona particular é anexada à rede VPC do consumidor.
• Os recursos de endpoint do Private Service Connect (endereço IP interno estático e regra de encaminhamento) e o anexo de rede são criados em SERVICE_PROJECT_ID. Cada um desses comandos usa uma referência entre projetos à sub-rede compartilhada ou à rede VPC em HOST_PROJECT_ID. Em uma implantação de projeto único, SERVICE_PROJECT_ID e HOST_PROJECT_ID são iguais, então não há mudanças de propriedade entre as etapas. Para mais informações sobre o modelo de VPC compartilhada para endpoints do Private Service Connect, consulte Criar um endpoint em um projeto de serviço de VPC compartilhada.

Criar uma zona particular do Cloud DNS

Crie uma zona particular do Cloud DNS visível apenas para sua VPC de consumo. O agente usa essa zona (via peering de DNS) para resolver APIGEE_HOSTNAME em um endereço IP particular.

gcloud dns managed-zones create apigee-private \
  --project=HOST_PROJECT_ID \
  --dns-name="PARENT_DNS_NAME" \
  --description="Private zone for Apigee PSC access" \
  --visibility=private \
  --networks=VPC_NAME

Para mais informações sobre zonas particulares do Cloud DNS, consulte Zonas particulares.

Criar um anexo de rede

Crie um anexo de rede na mesma região e sub-rede em que você quer que a interface PSC do Agent Runtime apareça. O Agent Runtime vincula a interface do PSC a esse anexo quando o agente é implantado.

Em uma implantação de projeto único, crie o anexo de rede em SERVICE_PROJECT_ID (que também é HOST_PROJECT_ID). Em uma implantação de VPC compartilhada, é possível criar o anexo de rede no projeto de serviço ou no projeto host. O Agent Platform recomenda o projeto de serviço para simplificar as permissões. Para orientações sobre como escolher e os papéis do IAM correspondentes, consulte Usar a interface do Private Service Connect com a VPC compartilhada.

O comando a seguir cria o anexo de rede em SERVICE_PROJECT_ID. Em uma implantação de VPC compartilhada, a referência de sub-rede precisa incluir o ID do projeto host.

gcloud compute network-attachments create agent-network-attachment \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --subnets=projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME \
  --connection-preference=ACCEPT_AUTOMATIC

Reservar um endereço IP interno e estático

Reserve um endereço IP interno para usar como o IP do endpoint do Private Service Connect a que o agente se conecta. Crie o recurso de endereço em SERVICE_PROJECT_ID e faça referência à sub-rede compartilhada em HOST_PROJECT_ID para que o valor do endereço seja alocado do intervalo dessa sub-rede. Isso corresponde às orientações da VPC compartilhada em Usar um endereço IP interno estático com a VPC compartilhada.

gcloud compute addresses create apigee-psc-endpoint-ip \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --subnet=projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME

Recupere o endereço reservado, que será usado nas próximas etapas:

gcloud compute addresses describe apigee-psc-endpoint-ip \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --format="value(address)"

Este documento se refere a esse endereço como PSC_ENDPOINT_IP.

Acessar o anexo de serviço da instância da Apigee

Recupere o URI do anexo de serviço da sua instância da Apigee usando o método organizations.instances.get da API Apigee. Use esse URI como destino do endpoint do Private Service Connect.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME"

A resposta inclui um campo serviceAttachment. Este documento se refere a esse valor como APIGEE_SERVICE_ATTACHMENT. Para mais informações sobre como o Apigee expõe um anexo de serviço em cada instância, consulte Gerenciar instâncias.

Criar o endpoint do Private Service Connect

Crie uma regra de encaminhamento que funcione como o endpoint do Private Service Connect. Ele tem como destino o anexo de serviço do Apigee e usa o IP estático que você reservou. Crie a regra de encaminhamento em SERVICE_PROJECT_ID e faça referência à rede VPC compartilhada em HOST_PROJECT_ID e ao endereço em SERVICE_PROJECT_ID.

gcloud compute forwarding-rules create apigee-psc-endpoint \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --network=projects/HOST_PROJECT_ID/global/networks/VPC_NAME \
  --address=projects/SERVICE_PROJECT_ID/regions/REGION/addresses/apigee-psc-endpoint-ip \
  --target-service-attachment=APIGEE_SERVICE_ATTACHMENT

Verifique se o serviço da Apigee aceitou a conexão:

gcloud compute forwarding-rules describe apigee-psc-endpoint \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --format="value(pscConnectionStatus)"

O status precisa ser ACCEPTED para que o endpoint possa encaminhar o tráfego. Para mais informações sobre endpoints do Private Service Connect, consulte Sobre como acessar serviços publicados por meio de endpoints.

Adicionar um registro DNS para o nome do host

Na zona particular, crie um registro A que resolva APIGEE_HOSTNAME para PSC_ENDPOINT_IP. Esse registro só é visível dentro de VPC_NAME, então os clientes externos continuam resolvendo o nome do host pelo DNS público.

gcloud dns record-sets create APIGEE_HOSTNAME. \
  --project=HOST_PROJECT_ID \
  --zone=apigee-private \
  --type=A \
  --ttl=60 \
  --rrdatas=PSC_ENDPOINT_IP

Etapa 2: configurar a Apigee

Adicionar o projeto de serviço à lista de aceitação do consumidor da instância

A instância do Apigee só aceita conexões do Private Service Connect de projetos de consumidores que estão no consumerAcceptList. O lado do consumidor da conexão está associado a SERVICE_PROJECT_ID, porque é o projeto em que o agente é implantado.

Por padrão, o projeto associado à organização da Apigee (APIGEE_PROJECT_ID) já está na lista. Se SERVICE_PROJECT_ID for igual a APIGEE_PROJECT_ID, não será necessário fazer mudanças. Você pode pular esta seção. Caso contrário, adicione SERVICE_PROJECT_ID à lista.

Primeiro, verifique o valor atual de consumerAcceptList usando o método organizations.instances.get:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME"

Procure o campo consumerAcceptList na resposta.

Em seguida, atualize a lista chamando o método organizations.instances.patch com uma máscara de atualização em consumerAcceptList. Como o campo substitui a lista atual, inclua todos os ID do projeto que precisam manter o acesso, incluindo APIGEE_PROJECT_ID e outros projetos de serviço que implantam agentes:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"consumerAcceptList": ["APIGEE_PROJECT_ID", "SERVICE_PROJECT_ID"]}' \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME?updateMask=consumerAcceptList"

Confirme a atualização executando o comando get novamente e verificando se SERVICE_PROJECT_ID agora está incluído em consumerAcceptList.

Alternativa:também é possível adicionar ou remover projetos aceitos usando o console Google Cloud . Consulte Editar a lista de projetos aceitos em Como gerenciar instâncias.

Verificar o nome do host do grupo de ambientes

Confirme se APIGEE_HOSTNAME está listado no grupo de ambiente que hospeda seus proxies de API. Se não estiver, adicione.

Para instruções, consulte Como trabalhar com grupos de ambiente.

Etapa 3: implante o agente com uma interface do PSC e peering de DNS

Ao implantar o agente no Agent Runtime, configure-o com uma interface PSC que faz referência ao anexo de rede criado e configure o peering de DNS para sua zona particular. Para conferir o procedimento completo de implantação e os frameworks compatíveis, consulte Usar a interface do Private Service Connect com o Agent Runtime e Implantar agentes na documentação da Agent Platform.

Configure os dois campos a seguir na configuração da interface do PSC do agente (consulte a referência PscInterfaceConfig):

• networkAttachment: defina como o nome completo do recurso do anexo de rede que você criou na Etapa 1, no formato projects/SERVICE_PROJECT_ID/regions/REGION/networkAttachments/agent-network-attachment. Se você criou o anexo de rede no projeto host, use HOST_PROJECT_ID neste caminho.
• dnsPeeringConfigs: adicione uma entrada com os seguintes campos para que o Agent Runtime resolva APIGEE_HOSTNAME pela sua zona particular:
  • domain: PARENT_DNS_NAME. O valor precisa terminar com um ponto.
  • targetProject: HOST_PROJECT_ID. Este é o projeto que contém a VPC do consumidor e a zona particular.
  • targetNetwork: VPC_NAME.

O agente de serviço do Agent Platform para SERVICE_PROJECT_ID ([e-mail]) precisa ter permissão para configurar o peering de DNS e atualizar o anexo de rede. Conceda os papéis necessários conforme descrito em Papel necessário do agente de serviço da plataforma do agente. Em uma implantação de VPC compartilhada, outras funções se aplicam ao projeto host. Consulte Usar a interface do Private Service Connect com a VPC compartilhada.

No código do agente, chame o proxy de API em https://APIGEE_HOSTNAME/BASE_PATH. No ambiente de execução do Agent Runtime, esse nome do host é resolvido por peering de DNS para PSC_ENDPOINT_IP, e a solicitação atravessa o endpoint do Private Service Connect até sua VPC e para o Apigee.

Observação:como a instância do Apigee apresenta um certificado autoassinado no caminho particular, o cliente HTTP do agente precisa aceitar certificados autoassinados ou usar uma configuração que coloque um balanceador de carga de aplicativo interno com um certificado TLS gerenciado na frente da vinculação de serviço. Consulte Rede no sentido norte com o Private Service Connect para a variante com balanceamento de carga.

Verificar o caminho privado

Depois de implantar o agente, verifique se as solicitações chegam à Apigee pelo caminho particular:

• Confirme se o status da regra de encaminhamento é ACCEPTED usando o comando em Criar o endpoint do Private Service Connect.
• Em uma VM do Compute Engine anexada a VPC_NAME em REGION (em uma implantação de VPC compartilhada, essa VM pode estar no projeto host ou em um projeto de serviço anexado à VPC compartilhada), execute dig +short APIGEE_HOSTNAME. O resultado precisa ser PSC_ENDPOINT_IP. Isso confirma que a zona particular resolve o nome do host corretamente dentro da VPC.
• Na mesma VM, envie uma solicitação para um proxy de API implantado em https://APIGEE_HOSTNAME/BASE_PATH e confirme se você recebe a resposta esperada.
• Invoque o agente implantado e confirme se a solicitação foi atendida. Em seguida, use o Apigee Analytics ou o Debug para confirmar se a solicitação chegou ao proxy de API esperado no nome do host do grupo de ambiente.

A seguir

• Saiba mais sobre Como usar a interface do Private Service Connect com o Agent Runtime.
• Saiba como implantar agentes no Agent Runtime.
• Leia sobre Redes na direção norte com o Private Service Connect, a variante baseada em balanceador de carga que usa um certificado TLS gerenciado.
• Leia sobre os padrões de rede no sentido sul, que descrevem como a Apigee se conecta de maneira particular aos seus destinos de back-end.
• Saiba mais sobre o MCP na Apigee para expor suas APIs como ferramentas do MCP a aplicativos de agentes.