Chapter 2 of 6
Architecture at a glance#
The caller sends a Microsoft Entra application token and an APIM subscription key. APIM validates both, applies limits and Content Safety, then exchanges the caller authority for its system-assigned managed-identity token. It calls the pinned Foundry agent through the approved backend. Application Insights receives correlation and token metrics without request or response bodies.
gateway-design-record.json records the target scope, backend, identities, network paths, runtime controls, restore path, owners, and readiness gaps. The combined preflight runs its local record check before it reads Azure or proposes the deployment.
Design choices and tradeoffs#
| Decision | Chosen approach | Cost and limitation |
|---|---|---|
| Client access | Entra application token plus one APIM subscription per workload | Clients manage both credentials |
| Backend identity | APIM managed identity with Foundry Agent Consumer on one agent | Direct Foundry access needs its own control |
| Safety | APIM Content Safety before the agent RAI policy | It adds latency and a data path |
| Routing | Primary backend with one read-safe retry | Secondary routing stays disabled |
| Telemetry | Correlation and token metrics with body logging disabled | Content is unavailable for debugging |
The retry is safe because the governed agent has a read-only tool.