Citadel contracts
The citadel architecture contains a central governance hub that agents must use to communicate with AI asset backends:
- centrally managed LLMs
- tools, such as MCP servers
- other agents (e.g. via the A2A protocol)
In the Citadel architecture, this governance is contract-driven. The general philosophy is "separation of concerns with unified oversight".
Platform teams manage backends. Business teams manage their own access contracts.
The main responsibility of the governance hub is runtime enforcement.
Schematically:
┌───────────────────────────────── CONSUMERS ─────────────────────────────────┐
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Agent │ │ LLM-app │ │ MCP-host │ │
│ │ (autonomous) │ │ (chat, RAG) │ │ (IDE, assistant) │ │
│ └──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ │
│ │ │ │ │
└──────────┼───────────────────────┼─────────────────────────┼────────────────┘
│ A2A / LLM API │ LLM API │ MCP
▼ ▼ ▼
┌─────────────────────────── GOVERNANCE HUB / GATEWAY ────────────────────────┐
│ │
│ Identity & Auth Policy & Guardrails Routing & Registry │
│ ───────────────── ────────────────────── ────────────────────────── │
│ • authN (OIDC) • allow/deny per tool • model routing / fallback │
│ • authZ / scopes • PII / DLP filtering • MCP server catalogue │
│ • token exchange • prompt-inj. checks • agent cards (A2A) │
│ │
│ Quotas & Cost Observability & Audit Lifecycle │
│ ───────────────── ────────────────────── ────────────────────────── │
│ • rate limits • traces / logs • versioning / approval │
│ • token budgets • audit trail • onboarding / revocation │
│ │
└──────────┬───────────────────────┬─────────────────────────┬────────────────┘
│ LLM API │ MCP │ A2A
▼ ▼ ▼
┌──────────────────────────────── PROVIDERS ──────────────────────────────────┐
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ LLMs │ │ Tools │ │ Other agents │ │
│ │ hosted / OSS │ │ (MCP servers,│ │ (A2A-speaking, │ │
│ │ / internal │ │ APIs, data)│ │ internal / ext.)│ │
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Contract types: backend, access, publish
Contracts come into play at both sides of the gateway:
- Access contracts: Who may access a onboard use-cases and agents and describe which backend resources a consumer may use and which governance policies apply
- Backend contracts: Where do LLM requests route to?
- Publish contracts: What AI assets (tools/agents) are published and centrally protected?
- Publishing does not grant any access
Contracts are managed as infrastructure-as-code (IaC).
The governance hub is (at the moment of writing) supported by Azure API Management (APIM) as the gateway.
N.B. all Microsoft documentation on this topic uses several terms, which can be very confusing. There are "AI landing zones" (reference architecture with solution accelerator code?) for the AI Governance Hub, which is layer 1 of the "AI Citadel Blueprint". The AI Governence Hub is implemented using APIM as a "unified AI gateway" or "runtime gateway".
Q: Why is there a separate backend contract conceptually? It seems the publish contract governs MCP and A2A, but why not LLMs?
It seems this (arbitrary) distinction is made because the backend contract leverages the APIM backend feature, including things like load balancing and failover?
Publish contracts
Backend contracts
Access contracts
Principles extracted from these docs:
- Each service gets its own APIM product that grants access to backend resources
- Backend resources can be of mixed types: LLM, tool/MCP server, A2A speaking agents.
- The respective APIs providing access to these servers need to be added automatically to the APIM product
- APIM product policies are applied conditionally on the asset type
- In the case of agents, a Foundry connection needs to be created to connect to an agent that also requires LLM access
- TODO: I assume this is needed because agents need to be configured in Azure Foundry with an LLM-connection, so this doesn't work by managing LLM-access and agent access separately?
WIP
Assumptions:
- Everything is managed in IaC
- Meaning the service principal deploying this needs full rights to the gateway resources.
- Can make APIM backends
- Can make Foundry connections between APIM and Foundry
- Make and use APIM policy fragments
How to access and publish contracts play nice together?
pass
Contracts and policies
The contracts
https://github.com/Azure-Samples/ai-hub-gateway-solution-accelerator/blob/main/bicep/infra/citadel-access-contracts/citadel-access-contracts-policy.md