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

See Citadel publish contracts

Backend contracts

See Citadel backend contract

Access contracts

Ref

See Citadel access contract

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