cleandataengineering.aiAgent Harness, drawn simply
You are here: Architecture › On Azure

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.

The dark box is our hand-written loop. Cells with a small circle open the design page for that piece.

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:

DecisionChosenAlso 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 file
bindings:
  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.

Look inside