A disponibilidade de modelos no Microsoft Foundry varia por região. Pode ser que a região aprovada para seu projeto não ofereça o modelo ou o suporte do Foundry Agent Service necessário. Isso gera uma decisão de arquitetura: conectar-se diretamente a outro recurso Foundry, ou adicionar uma camada de gateway para mais controle e governança. Este artigo complementa a documentação oficial Bring Your Own Model com foco em cenários cross-region, tradeoffs e padrões de implantação empresarial.
TL;DR: O Microsoft Foundry oferece duas formas suportadas de acessar modelos entre regiões: conexão direta a outro recurso Foundry, ou via Azure API Management (APIM) como gateway. A escolha depende da necessidade de governança, roteamento e observabilidade. Este artigo detalha a implementação do padrão APIM em uma topologia VNet-secured, com autenticação por managed identity, tráfego privado via private endpoints e compatibilidade parcial com ferramentas como avaliações e Content Safety.
Qual padrão de conectividade cross-region escolher?
A imagem abaixo mostra os dois padrões principais: conexão direta (sem gateway) e Azure API Management como AI Gateway.
Conexão Direta (sem gateway)
Use quando o objetivo é alcançar modelos em outro recurso Foundry com o mínimo de componentes.
Azure API Management AI Gateway
Use quando o time de plataforma deseja uma superfície governada e um plano de controle próprio na frente do tráfego de modelos.
Variante VNet-secured com APIM
Nesta variante, o APIM tem seu inbound também atrás de um private endpoint no VNet do projeto. Toda a requisição (caller → APIM → backend) trafega na backbone Azure sem nenhum hostname público.
Tabela Comparativa dos Padrões
| Padrão | Melhor para | Modelo de controle e autenticação | Tradeoffs |
|---|---|---|---|
| Conexão direta a outro Foundry | Equipes que precisam do caminho mais simples, sem gateway adicional | A conexão aponta diretamente para o endpoint do Foundry backend. Autenticação via API key ou managed identity. | Menor sobrecarga arquitetural, mas sem camada de política, roteamento ou observabilidade centralizada. |
| Conexão via Azure API Management | Times de plataforma que querem um gateway estável com roteamento, throttling e telemetria | A conexão aponta para o endpoint APIM, que normaliza autenticação, aplica políticas e encaminha ao backend. | Adiciona um hop a mais e exige design do APIM, planejamento de subnets e ownership operacional. |
| APIM na frente da superfície do agente | Governança e telemetria no ingress do agente (throttling, logging, validação de schema) | O tráfego de entrada passa pelo APIM, mas o Foundry continua validando o token do caller diretamente (MCP OBO). | APIM não substitui a identidade na superfície do agente – deve ser tratado como camada de governança, não de autenticação. |
Na prática, as equipes têm duas formas suportadas de acessar modelos entre regiões. Conexão direta é o ponto de partida mais simples. O APIM é útil quando a plataforma quer governança centralizada. A escolha depende de ownership, necessidade de controle e overhead operacional.
O que esta arquitetura prova: agents, modelos e tracing continuam funcionando
Essa arquitetura responde a uma pergunta chave: a experiência se mantém íntegra quando os modelos são alcançados cross-region através de um gateway? Sim. Tanto Foundry agents (com estado no Playground) quanto prompt agents (invocações via Responses API) executam end-to-end contra modelos alcançados via APIM.
Os fluxos operacionais permanecem intactos. O tracing do APIM mostra a URL do backend reescrita e o caminho do token de managed identity. Valores por requisição como apim-request-id e apim-trace-id fluem pela telemetria padrão do APIM. A política de roteamento é reutilizável entre deployments porque o caminho /inference/deployments/{deploymentName}/chat/completions é parametrizado. Para expor um novo modelo, basta implantá-lo no Foundry backend e registrá-lo na configuração do AI Gateway no projeto.
Dynamic Connection
Para roteamento baseado em payload (Responses API, que carrega o nome do modelo no corpo JSON), o Foundry oferece a dynamic model connection: ela resolve model → backend no lado do projeto no momento da invocação. A vantagem é que o APIM nunca precisa inspecionar o corpo; a desvantagem é que a decisão de roteamento sai do APIM, então a URL observável única não cobre mais todas as chamadas. Times que adotam a Responses API em escala devem combinar APIM (para acesso backend + managed identity) com a dynamic connection (para despacho por chamada).
Compatibilidade de funcionalidades BYOM via APIM (na data de publicação)
A tabela abaixo resume como as funcionalidades atuais do Foundry interagem com BYOM via APIM. A experiência continua evoluindo.
| Funcionalidade Foundry | Status com BYOM via APIM | Notas |
|---|---|---|
| Chat completions / Responses API | ✅ Funciona | Ambas as superfícies invocam a conexão BYO; APIM encaminha e retorna a resposta sem alterações. |
| Foundry agents (Assistants / Threads / Runs) | ✅ Funciona | O estado do agente fica no projeto; apenas a chamada do modelo atravessa o APIM. |
| Prompt agents (Responses API) | ✅ Funciona | Invocações passam pela conexão BYO a cada chamada. |
| Ferramentas 1P on-behalf-of (SharePoint Grounding, Fabric Data Agent, etc.) | ❌ Não suportado | Foundry retorna bad_request porque o contexto de tenant 1P vazaria para fora do limite de confiança da Microsoft. Use conexão direta ou divida em dois agents. |
| Avaliações offline (sobre dataset) | ⚠️ Parcial | Avaliações que chamam o modelo via BYO funcionam, mas métricas de introspecção (token-level scoring, log-probs) podem degradar. |
| Avaliações contínuas (produção) | ⚠️ Parcial | Mesma limitação das avaliações offline. |
| Red teaming / testes adversarial | ✅ Funciona | Sondas são em nível de payload; nenhum hook first-party necessário. |
| Foundry IQ (sugestões de avaliação) | ⚠️ Fidelidade reduzida | Recomendações são mais grosseiras porque o tráfego BYO aparece como uso opaco em nível de conexão. |
| Content Safety no Foundry Control Plane | ⚠️ Configurar no APIM | Filtros do Foundry não se aplicam automaticamente a conexões BYO. Anexe a política Content Safety no APIM. |
| Prompt Shields (jailbreak / injeção indireta) | ⚠️ Configurar no APIM | Mesmo caso: anexe a política Prompt Shields no APIM. |
| Fine-tuning | ❌ Não aplicável à conexão | Fine-tuning é feito diretamente no deployment do Foundry backend; o APIM não participa. |
| Batch API | ⚠️ Apenas direto | Jobs batch usam APIs de longa duração que não cabem no modelo síncrono do APIM. Submeta batch diretamente contra o backend Foundry. |
Topologia de Exemplo: APIM em VNet e Componentes Core
Esta implementação usa dois recursos Foundry com papéis distintos. O recurso do projeto (project-side) hospeda o agente na região aprovada, integrado à VNet. O recurso backend hospeda os modelos na região de capacidade, exposto apenas via private endpoint. O APIM fica entre eles como gateway gerenciado, com DNS privado resolvendo os FQDNs do backend para IPs privados.
| Componente | Recurso | Notas |
|---|---|---|
| Project resource | <foundry-account> / <project-name> (ex.: canadaeast) |
Hospeda o projeto do agente. Integrado à VNet, usa system managed identity. |
| APIM AI Gateway | <apim-name> (StandardV2) |
Gateway gerenciado. Sua managed identity recebe a role Cognitive Services User no backend para encaminhar chamadas sem API keys. |
| Backend account | <backend-account> (ex.: japaneast) |
Hospeda os modelos. Após setup, public network access é desabilitado. |
| Private endpoint | <backend-account>-pe na subnet backend-pe |
Caminho privado cross-region. DNS privado resolve o hostname do backend para o endpoint privado. |
| AI Gateway connection | <connection-name> no projeto |
Conexão usada pelo projeto para enviar chamadas ao APIM com managed identity e lista de modelos disponíveis. |
Juntos, esses componentes tornam o padrão prático para produção: nomes de serviço resolvem privadamente, acesso público desabilitado, autenticação por managed identity, e todos os modelos alcançáveis por uma única URL observável.
O que está realmente dentro da VNet hoje
Hoje, a VNet do projeto contém quatro subnets:
- agent-subnet — delegada a Microsoft.App/environments para o runtime do agente.
- pe-subnet — private endpoints para o Foundry account, Storage, Cosmos DB, AI Search.
- apim-outbound — integração outbound do APIM SV2, sem acesso de saída público implícito.
- backend-pe — private endpoint cross-region para o Foundry account backend, também sem acesso de saída público.
A tabela abaixo mostra a cadeia de autenticação hop a hop:
| Hop | Artefato de auth | Identidade usada | Configurado por |
|---|---|---|---|
| Agent → Project | Nenhum (in-process) | n/a | Foundry SDK |
| Project → APIM | Token AAD bearer | Managed identity do projeto | Política validate-azure-ad-token (precisa do projectMiClientId) |
| APIM → Backend | Token AAD bearer novo | Managed identity do APIM | Política authentication-managed-identity + role Cognitive Services User |
| Caminho de rede | Privado o tempo todo | n/a | Backend publicNetworkAccess: Disabled; resolução via zonas DNS privatelink |
Nenhuma API key é armazenada. Nenhuma subscription key do APIM é necessária. A rotação de tokens é automática pelas managed identities.
Como consumir a conexão a partir de um agente
Uma vez que a conexão existe, qualquer superfície do Foundry que aceite um nome de deployment — agents, prompt agents, chamadas chat-completions e Responses do SDK, Playground — aceita o alias <connection-name>/<deployment-name>:
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
project = AIProjectClient(
endpoint="https://<foundry-account>.services.ai.azure.com/api/projects/<project-name>",
credential=DefaultAzureCredential(),
)
agent = project.agents.create_agent(
model="ai-gateway/gpt-5", # <connection-name>/<deployment-name>
name="cross-region-agent",
instructions="You are a helpful assistant.",
)
Próximos Passos
- Bring your own model with the AI Gateway — Padrão BYOM canônico para Foundry Agent Service.
- Configure AI Gateway in your Foundry resources — Ative o APIM como gateway no portal.
- AI gateway capabilities in Azure API Management — Políticas, throttling e observabilidade para tráfego de IA.
- Import a Microsoft Foundry API — Traga um endpoint Foundry para dentro do APIM.
- Microsoft Foundry documentation — Explore a plataforma completa.
Deployment Walkthrough
A implementação completa está no repositório: foundry-samples/infrastructure/infrastructure-setup-bicep/16-private-network-standard-agent-apim-setup/extensions/byom-cross-region
Pré-requisitos
- Azure CLI 2.67+ e PowerShell 7+
- Assinatura Azure com Contributor no resource group alvo
- Módulo Az PowerShell (Install-Module Az -Scope CurrentUser)
- Owner ou Contributor + User Access Administrator no resource group (o template cria role assignments)
- Foundry Account Owner para criar a conta Foundry
- Quota para gpt-4o/gpt-5/gpt-5.1 na região backend e gpt-4o na região do projeto
- Quota para APIM StandardV2 na região do projeto
- O client ID da managed identity do projeto Foundry (projectMiClientId) — necessário para o APIM validar tokens de entrada
Deploy
git clone https://github.com/azure-ai-foundry/foundry-samples.git
cd foundry-samples/samples/microsoft/infrastructure-setup/16-private-network-standard-agent-apim-setup/extensions/byom-cross-region
az group create --name <rg> --location <project-region>
az deployment group create \
--resource-group <rg> \
--template-file main.bicep \
--parameters @samples/parameters-cross-region.json \
--parameters projectMiClientId=<paste-client-id>
Após o deploy, a URL do gateway está em outputs.apimGatewayUrl. Os modelos conectados aparecem no portal como <connection-name>/<deployment-name> (ex.: ai-gateway/gpt-5).
Smoke Test
A API /inference tem subscriptionRequired: false. Para verificar o gateway:
$apim = '<your-apim-name>'
$deployment = 'gpt-5'
$token = az account get-access-token --resource 'https://cognitiveservices.azure.com' --query accessToken -o tsv
$body = @{ messages = @(@{ role = 'user'; content = 'Say hi in five words.' }); max_tokens = 30 } | ConvertTo-Json -Compress
Invoke-RestMethod -Method POST `
-Uri "https://$apim.azure-api.net/inference/deployments/$deployment/chat/completions?api-version=2024-10-21" `
-Headers @{ Authorization = "Bearer $token"; 'Content-Type' = 'application/json' } `
-Body $body
Um 200 com os headers x-aigw-backend e x-aigw-region comprova que a cadeia de políticas (validação MI → reescrita do backend → private endpoint cross-region) está saudável.
Apêndice — O que o trace do APIM prova
Um POST real contra /inference/deployments/gpt-4o/chat/completions confirma a cadeia:
Inbound
authentication-managed-identity -> token acquired for https://cognitiveservices.azure.com
set-header Authorization -> Bearer token from APIM SMI, not the caller
set-header api-key (delete) -> removed
set-backend-service -> https://ctcfvce-jpe.openai.azure.com/openai
set-header x-aigw-route -> customer-apim-fvce to japaneast
Backend
request-forwarder -> POST /openai/deployments/gpt-4o/chat/completions
forward-request -> 200 OK, x-ms-region: Japan East
Outbound
set-header x-aigw-backend -> apim-fvce-aigw / ctcfvce-jpe
set-header x-aigw-region -> canadaeast to japaneast
transfer-response -> response sent to caller in full
Perguntas Frequentes
-
Quais são as opções para conectar modelos do Foundry entre regiões?
Duas opções principais: conexão direta a outro recurso Foundry (mais simples, sem gateway adicional) e conexão via Azure API Management (APIM), que adiciona um gateway gerenciado para políticas, roteamento, throttling e observabilidade. -
O APIM pode ser usado em uma VNet com endpoints privados?
Sim. O artigo descreve uma variante VNet-secured onde o APIM tem inbound via private endpoint no VNet do projeto, e o backend Foundry é acessado por outro private endpoint cross-region, mantendo todo o tráfego na backbone Azure sem exposição pública. -
Quais funcionalidades do Foundry não funcionam com BYOM via APIM?
Ferramentas first-party on-behalf-of (como SharePoint Grounding e Fabric Data Agent) não são suportadas. Avaliações (offline e contínuas) funcionam parcialmente, com métricas de introspecção degradadas. Fine-tuning e Batch API devem ser feitos diretamente no backend Foundry. -
Como é feita a autenticação no padrão APIM cross-region?
A autenticação é end-to-end via managed identity: o projeto Foundry envia um token AAD para o APIM, que valida o token, obtém um novo token com sua própria managed identity e encaminha a requisição ao backend Foundry. Nenhuma API key é armazenada. -
Como consumir um modelo cross-region a partir de um agente Foundry?
Basta usar o alias/ (ex.: "ai-gateway/gpt-5") no parâmetro model do agente. O SDK do Foundry aceita esse formato em agents, prompt agents, chat completions e no Playground.
Artigo originalmente publicado por rayankhoury em Azure Updates - Latest from Azure Charts.
