Conectar o processador de extensão da Apigee a um gateway de agente

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Nesta página, descrevemos como conectar o processador de extensões da Apigee a um gateway de agente, para que as políticas da Apigee sejam aplicadas às chamadas que um agente de IA faz ao modelo, às ferramentas e aos servidores do Protocolo de Contexto de Modelo (MCP) que ele usa, sem mudar o agente.

Um gateway de agente é o ponto de entrada e saída de rede para o tráfego de um agente. Ele não é um balanceador de carga, então não usa uma extensão de tráfego. Em vez disso, o gateway delega a autorização a uma extensão de autorização, e você configura o processador de extensão como essa extensão. Depois de conectado, o gateway envia cada solicitação e resposta do agente para a Apigee processar, e a Apigee retorna um veredicto.

A figura a seguir mostra os recursos que você cria nesta página e o caminho que uma única solicitação de agente percorre por eles:

Uma solicitação de agente é mantida no Gateway de Agente, enviada à Apigee pelo Private Service Connect para um veredito e, em seguida, encaminhada.
Figura 1. Componentes e fluxo de solicitação quando o processador de extensão da Apigee é a extensão de autorização de um gateway de agente.

Na figura 1, uma solicitação é processada da seguinte maneira:

  1. O agente faz uma solicitação HTTPS comum para o modelo, uma ferramenta ou um servidor MCP. O agente é vinculado ao gateway quando é criado e não precisa de mudanças.
  2. O gateway retém a solicitação e chama a extensão de autorização para um veredito.
  3. A solicitação sai pelo anexo de rede, portanto, ela se origina dentro da sua rede VPC.
  4. Sua zona de DNS particular resolve o nome do host de callout para o endereço IP interno do endpoint do Private Service Connect.
  5. O endpoint encaminha a chamada para o anexo de serviço da sua instância da Apigee.
  6. O grupo de ambiente encaminha a callout pelo nome do host para o proxy sem destino, onde suas políticas são executadas.
  7. O proxy retorna um veredicto ao gateway. A Apigee nunca encaminha o tráfego do agente. O proxy não tem um destino.
  8. Se o veredicto permitir a solicitação, o gateway vai enviar a solicitação original para o destino.

Os AuthzPolicy e AuthzExtension na Figura 1 são configuração, não tráfego: a política anexa a extensão ao gateway, e a extensão nomeia o proxy do processador de extensão que é executado. Ambos são criados em Configurar a extensão de autorização.

Para conectar o processador de extensão a um balanceador de carga, consulte Começar a usar o processador de extensão da Apigee.

As seções a seguir orientam você nas etapas:

Antes de começar

Antes de começar, faça o seguinte:

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Apigee, Compute Engine, Network Services, Network Security, and Cloud DNS APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Apigee, Compute Engine, Network Services, Network Security, and Cloud DNS APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    8.

  8. Instale a CLI do Google Cloud.

    Depois de instalar a Google Cloud CLI, execute o comando gcloud components update para receber os componentes mais recentes da gcloud.

  9. Provisione uma instância do Apigee, caso ainda não tenha feito isso.

    No console do Google Cloud , acesse a página Instâncias da Apigee.

    Acessar "Instâncias da Apigee"

  10. Implante um Gateway de Agente na mesma região da sua instância do Apigee, com governedAccessPath definido como AGENT_TO_ANYWHERE para que o gateway governe o tráfego de saída do agente. Para mais informações, consulte Configurar o Gateway de Agente.

    Você vai atualizar a configuração de rede desse gateway mais tarde, em Atualizar o Gateway de Agente, depois que a zona de DNS existir.

  11. Confirme se você tem uma VPC e uma sub-rede que podem ser usadas pelo Gateway de Agente e pelo endpoint do Private Service Connect.

    Acessar redes VPC

Funções exigidas

Para receber as permissões necessárias para conectar o processador de extensão do Apigee a um gateway de agente, peça ao administrador para conceder a você os seguintes papéis do IAM:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Defina as variáveis de ambiente

Defina as variáveis de ambiente a seguir para identificar os recursos criados em Antes de começar. Cada seção posterior nesta página define as variáveis adicionais necessárias no ponto em que você cria o recurso nomeado.

export PROJECT_ID=PROJECT_ID
export ORG_NAME=$PROJECT_ID
export REGION=REGION
export INSTANCE=INSTANCE
export VPC_NETWORK_NAME=VPC_NETWORK_NAME
export SUBNET=SUBNET
export GATEWAY=GATEWAY

Em que:

  • PROJECT_ID é o ID do projeto que contém sua instância do Apigee.
  • REGION é a região Google Cloud da sua instância da Apigee.
  • INSTANCE é o nome da instância da Apigee.
  • VPC_NETWORK_NAME e SUBNET são a rede VPC e a sub-rede usadas pelo Gateway de Agente e pelo endpoint do Private Service Connect.
  • GATEWAY é o nome do Gateway de Agente que você implantou.

Para confirmar se as variáveis de ambiente estão definidas corretamente, execute o comando a seguir e analise a saída:

echo $PROJECT_ID $ORG_NAME $REGION $INSTANCE $VPC_NETWORK_NAME $SUBNET $GATEWAY

Escolha o nome do host da frase de destaque

O gateway acessa a Apigee em um nome de host particular escolhido por você. Você escolhe agora, antes de criar qualquer coisa, porque o primeiro recurso criado, o grupo de ambiente do Apigee, usa esse nome como nome do host. A zona de DNS que o resolve não é criada até Criar uma zona DNS particular.

export DNS_DOMAIN=DNS_DOMAIN
export EXTPROC_HOST=apigee-extproc.$DNS_DOMAIN

Em que DNS_DOMAIN é um domínio DNS particular que não precisa ser resolvido na Internet pública, escrito sem um ponto final, por exemplo, internal.example.com. Isso resulta em um EXTPROC_HOST de apigee-extproc.internal.example.com. Você pode usar um rótulo diferente de apigee-extproc, desde que o nome do host permaneça em DNS_DOMAIN.

Configurar um token de autenticação

export TOKEN=$(gcloud auth print-access-token)
echo $TOKEN

Configurar o processador de extensão da Apigee

Nomeie os recursos da Apigee que esta seção cria:

export EXTPROC_ENV=EXTPROC_ENV
export EXTPROC_ENVGROUP=EXTPROC_ENVGROUP
export PROXY_NAME=PROXY_NAME

Em que:

  • EXTPROC_ENV e EXTPROC_ENVGROUP são nomes escolhidos para um ambiente e um grupo de ambientes da Apigee dedicados ao processador de extensão, por exemplo, extproc-env e extproc-envgroup. Cada nome precisa ter de 2 a 32 caracteres de letras minúsculas, números ou hifens, começar com uma letra e não terminar com um hífen. O nome do ambiente precisa ser diferente de todos os outros nomes de ambiente na sua organização.
  • PROXY_NAME é um nome que você escolhe para o proxy do processador de extensão, por exemplo, extproc-authz.

A parte da configuração do Apigee é a mesma de um balanceador de carga. Siga Configurar o processador de extensões da Apigee no início rápido para:

  1. Crie um ambiente da Apigee com a propriedade apigee-service-extension-enabled definida como true, anexe-o à sua instância e crie um grupo de ambientes cujo nome de host seja $EXTPROC_HOST.
  2. Crie e implante um proxy de processador de extensão sem destino nesse ambiente.

Em seguida, liste as implantações no ambiente:

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments/$EXTPROC_ENV/deployments"

O ambiente pode ter mais de um proxy implantado. Portanto, na resposta, encontre a entrada em que apiProxy é $PROXY_NAME e anote o revision.

Você pode revisar o proxy no console Google Cloud :

Acessar proxies de API

Defina a seguinte variável para essa revisão, que você precisa em Verificar a conexão:

export REVISION=REVISION

Conectar o Gateway de Agente ao Apigee

O gateway alcança o Apigee por um endpoint do Private Service Connect na sua VPC, que ele encontra resolvendo $EXTPROC_HOST em uma zona de DNS particular.

Encontrar o anexo de serviço

Encontre o anexo de serviço da sua instância da Apigee:

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/instances"

Defina a seguinte variável como o valor serviceAttachment da instância na sua região:

export SERVICE_ATTACHMENT=SERVICE_ATTACHMENT

Criar um anexo de rede

O Gateway de Agente sai para sua VPC por um anexo de rede. Escolha um nome para ele, por exemplo, agent-gateway-attachment, e crie:

export NETWORK_ATTACHMENT=NETWORK_ATTACHMENT
gcloud compute network-attachments create $NETWORK_ATTACHMENT \
    --region=$REGION --subnets=$SUBNET --connection-preference=ACCEPT_AUTOMATIC

Criar o endpoint do Private Service Connect

Reserve um endereço IP interno e crie o endpoint do Private Service Connect:

gcloud compute addresses create apigee-extproc-psc-ip \
    --region=$REGION --subnet=$SUBNET --purpose=GCE_ENDPOINT
gcloud compute forwarding-rules create apigee-extproc-psc-endpoint \
    --region=$REGION --network=$VPC_NETWORK_NAME \
    --address=apigee-extproc-psc-ip \
    --target-service-attachment=$SERVICE_ATTACHMENT

No console do Google Cloud , acesse a página Private Service Connect .

Acessar a página "Private Service Connect"

Confirme se o endpoint informa pscConnectionStatus: ACCEPTED e defina a seguinte variável como o endereço IP dela:

gcloud compute forwarding-rules describe apigee-extproc-psc-endpoint \
    --region=$REGION --format="value(pscConnectionStatus,IPAddress)"
export PSC_IP=PSC_IP

Se o status for PENDING, seu projeto não estará no consumerAcceptList da instância do Apigee, e a conexão não poderá ser aceita.

Criar uma zona de DNS particular

Crie uma zona de DNS particular para $DNS_DOMAIN e um registro A que resolva $EXTPROC_HOST para o endereço IP do endpoint:

gcloud dns managed-zones create extproc-zone \
    --dns-name=$DNS_DOMAIN. --visibility=private --networks=$VPC_NETWORK_NAME \
    --description="Apigee extension processor callout host"
gcloud dns record-sets create $EXTPROC_HOST. --type=A --ttl=300 \
    --rrdatas=$PSC_IP --zone=extproc-zone

Atualizar o Gateway de Agente

Atualize o Gateway de Agente em Antes de começar para que ele saia pelo anexo de rede e possa resolver a zona criada.

  1. Exporte a configuração atual:

    gcloud network-services agent-gateways export $GATEWAY \
    --location=$REGION --destination=agent-gateway.yaml

  2. Em agent-gateway.yaml, adicione o seguinte bloco networkConfig, substituindo cada marcador de posição pelo valor da variável de ambiente correspondente. O arquivo é editado diretamente, então as variáveis de shell não são substituídas aqui:

    networkConfig:
  egress:
    networkAttachment: projects/PROJECT_ID/regions/REGION/networkAttachments/NETWORK_ATTACHMENT
  dnsPeeringConfig:
    domains: [ DNS_DOMAIN. ]
    targetProject: PROJECT_ID
    targetNetwork: projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME

    Deixe o restante do arquivo, incluindo googleManaged.governedAccessPath, protocols e registries, como exportado.

  3. Importe a configuração editada:

    gcloud network-services agent-gateways import $GATEWAY \
    --location=$REGION --source=agent-gateway.yaml

Para ver o conjunto completo de campos do Gateway de Agente, consulte Configurar o Gateway de Agente.

Configurar a extensão de autorização

Dois recursos conectam o gateway ao proxy do processador de extensão: uma extensão de autorização que aponta para a Apigee e uma política de autorização que anexa a extensão ao gateway.

Criar a extensão de autorização

Escolha um nome para a extensão de autorização, por exemplo, apigee-authz-extension. Os campos metadata selecionam qual proxy do Apigee é executado e se os corpos das mensagens são enviados a ele:

export AUTHZ_EXT=AUTHZ_EXT
cat > authz-extension.yaml <<EOF
name: projects/$PROJECT_ID/locations/$REGION/authzExtensions/$AUTHZ_EXT
authority: $EXTPROC_HOST
service: $EXTPROC_HOST
timeout: 5s
metadata:
  apigee-extension-processor: $PROXY_NAME
  apigee-request-body: 'true'
  apigee-response-body: 'true'
EOF
gcloud service-extensions authz-extensions import $AUTHZ_EXT \
    --source=authz-extension.yaml --location=$REGION

Em que:

  • O apigee-extension-processor seleciona o proxy do processador de extensão que processa o tráfego.
  • apigee-request-body e apigee-response-body disponibilizam os corpos de solicitação e resposta no proxy como request.content e response.content. Sem elas, as políticas que inspecionam o payload não encontram nada.

Criar a política de autorização

Escolha um nome para a política de autorização, por exemplo, apigee-content-authz-policy. A política anexa a extensão ao gateway e determina qual tráfego é enviado para a Apigee:

export AUTHZ_POLICY=AUTHZ_POLICY
cat > authz-policy.yaml <<EOF
name: projects/$PROJECT_ID/locations/$REGION/authzPolicies/$AUTHZ_POLICY
action: CUSTOM
policyProfile: CONTENT_AUTHZ
customProvider:
  authzExtension:
    resources:
    - projects/$PROJECT_ID/locations/$REGION/authzExtensions/$AUTHZ_EXT
httpRules:
- to:
    operations:
    - paths:
      - prefix: "/"
target:
  resources:
  - projects/$PROJECT_ID/locations/$REGION/agentGateways/$GATEWAY
EOF
gcloud beta network-security authz-policies import $AUTHZ_POLICY \
    --source=authz-policy.yaml --location=$REGION

Use policyProfile: CONTENT_AUTHZ para que os corpos das mensagens sejam inspecionados. Uma política REQUEST_AUTHZ avalia apenas os cabeçalhos de solicitação.

Verifique a conexão

Para gerar tráfego, você precisa de um agente cuja saída seja regida por esse gateway. Um agente é vinculado a um gateway quando é criado, definindo a configuração do Gateway de Agente como $GATEWAY. Não é possível exercer a conexão com uma solicitação HTTP direta ao gateway. Para mais informações, consulte Configurar o Gateway de Agente.

Inicie uma sessão de depuração do Apigee no proxy do processador de extensões e envie uma solicitação pelo agente:

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments/$EXTPROC_ENV/apis/$PROXY_NAME/revisions/$REVISION/debugsessions?timeout=600" \
  -d '{"count":15,"tracesize":5120,"filter":"(request.uri Like \"*generateContent*\")"}'

Nas transações capturadas, confirme se:

  • o URL da solicitação é o endereço chamado pelo agente, como o endpoint do modelo ou um host de ferramenta, em vez de um caminho base da Apigee;
  • request.content e response.content são preenchidos, o que confirma que os metadados do corpo na extensão de autorização estão funcionando.

Se nenhuma transação aparecer, verifique se o nome do host do grupo de ambiente, o registro DNS e os campos authority e service da extensão são todos $EXTPROC_HOST, se o endpoint do Private Service Connect informa ACCEPTED e se o governedAccessPath do gateway é AGENT_TO_ANYWHERE.

A seguir