Agent Harness Tutorial · Architecture
The agent harness on Azure, on one page
The same architecture with names in it. Each box is either an Azure managed service, an open-source tool run on Azure, or our own code where no product covers the job. The rule from the Series: the specs fix the concern and the port; Azure only fills the binding.
What runs in the demo today is a little smaller than this target. The model behind APIM is openai/gpt-oss-120b on Groq (free tier), not Foundry; the chat is a simple web page, not Chatwoot; A2A, Teams cards, Prometheus and Grafana are in the design but not running. Everything else on this page is live.
Four decisions come first, because everything else follows from them:
| Decision | Chosen | Also considered |
|---|---|---|
| A. Who owns the control loop? | Our hand-written loop on Container Apps, with Pydantic AI as the model layer | ◐ Microsoft Agent Framework · ✗ Foundry Agent Service prompt agent |
| B. How do we reach models? | APIM AI gateway | ✗ each agent calls the SDK itself |
| C. Who hosts the models? | Microsoft Foundry Models | |
| D. Where does our code run? | Azure Container Apps | ◐ AKS, only if needed |
Want every detail? The long version is in the Series: the agent harness on Azure, on one page.
How it is done: the real code
Cut from the live repositories each time the site is built, so it always matches what runs.
config/azure.yaml:16config/azure.yaml: every port's Azure binding, in one filebindings:
secrets:
adapter: key-vault
vault_url: {env: AZURE_KEY_VAULT_ENDPOINT}
# A6: the automatic payout limit and anything else that changes without a
# redeploy, read with the app's managed identity (App Configuration Data
# Reader) under the label `dev`, re-read every 30 s. The claims system reads
# the same key and label (config/claims-system/azure.yaml). A13: the kill
# switch, `agent.enabled` (label dev), read before every turn.
config:
adapter: app-configuration
endpoint: {env: AZURE_APP_CONFIGURATION_ENDPOINT}
label: dev
telemetry:
adapter: azure-monitor-otel
connection_string: {key_vault: appinsights-connection-string}
model:
adapter: apim-ai-gateway
base_url: {env: APIM_GROQ_BASE_URL}
api_key: {key_vault: apim-subscription-key}
state:
adapter: azure-postgresql-flexible
url: {key_vault: agent-database-url}
# A2: the sign-in's refresh tokens (agent_state.sessions), encrypted with a
# key derived from this secret; azd generates it and Bicep writes it.
session_key: {key_vault: agent-session-key}
records:
adapter: postgres
url: {key_vault: agent-database-url}
identity:
adapter: entra-id
tenant: {env: AZURE_TENANT_ID}
# A v2 access token's `aud` is the API's client id, not its api:// URI
# (FINDINGS F-55), so the agent's own app id, which the Entra hook records.