Citadel + AGT Integration Architecture¶

This document describes how the Agent Governance Toolkit (AGT) integrates with the Foundry Citadel Platform, Microsoft's layered architecture for AI governance.

Positioning¶

Citadel and AGT address different enforcement boundaries that are complementary, not competing:

How AGT Maps to Citadel's 4 Layers¶

AGT is not confined to a single Citadel layer. It spans the architecture:

┌─────────────────────────────────────────────────────────────────┐
│                    Foundry Citadel Platform                      │
│                                                                 │
│  Layer 4: Security Fabric (Defender, Purview, Entra)            │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  AGT trust scores surface as risk labels in Defender    │    │
│  │  AGT data_classification aligns with Purview labels     │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  Layer 3: Agent Identity (Agent 365 / Entra)                    │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  AGT agent identities federate with Entra agent IDs     │    │
│  │  Entra = enterprise identity, AGT = runtime credentials │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  Layer 2: AI Control Plane (Foundry Control Plane)              │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  AGT exports governance evidence and traces             │    │
│  │  Policy decisions enrich Foundry/OTEL traces            │    │
│  │  Fleet-wide compliance visibility via Azure Monitor     │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  Layer 1: Governance Hub (APIM Gateway)                         │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  Access Contracts reference AGT policy bundles          │    │
│  │  AGT metadata headers pass through APIM for correlation │    │
│  │  Gateway = coarse rules, AGT = action-level rules       │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

Layer 1: Governance Hub¶

Citadel's APIM gateway enforces infrastructure-level controls: which models an agent can access, at what rate, with what content safety filters. AGT integrates through Access Contract policy bundle binding: when a Citadel Access Contract provisions an agent environment, it references an AGT policy bundle ID/version. The agent runtime loads this bundle at startup.

Policy precedence: Gateway rules (rate limits, content filters, JWT) are enforced first at the APIM layer. AGT action-level policies are enforced second, inside the agent runtime. Both must pass for an action to proceed.

Layer 2: AI Control Plane¶

AGT's primary Layer 2 contribution is governance evidence and trace enrichment. The CitadelAuditExporter sends policy decisions, trust score changes, and action interception events to Azure Event Hub and Application Insights. These events include correlation IDs that tie AGT decisions to APIM request traces and Foundry execution traces, enabling unified observability dashboards.

Layer 3: Agent Identity¶

Entra ID / Agent 365 remains the authoritative source for enterprise agent identity and lifecycle management. AGT's Ed25519/SPIFFE identities remain authoritative for runtime cryptographic credentials. The integration is federation, not replacement: AGT trust scores (0-1000) surface as risk labels in telemetry, not as primary Entra metadata.

Layer 4: Security Fabric¶

AGT's data_classification labels on policies align with Purview sensitivity labels. AGT trust scores can surface as risk signals in Defender for AI. This integration is primarily through the telemetry pipeline (Layer 2 export) rather than direct API integration.

Data Flow¶

Agent Runtime                    Citadel Gateway              Azure Monitor
┌──────────────────┐            ┌──────────────────┐         ┌──────────────┐
│                  │            │                  │         │              │
│  Agent Code      │   LLM     │  APIM Gateway    │         │  App Insights│
│  ┌────────────┐  │  request  │  ┌────────────┐  │         │              │
│  │ AGT Policy ├──┼──────────►│  │ Rate Limit ├──┼────►LLM │  Event Hub   │
│  │ Engine     │  │           │  │ Content    │  │         │              │
│  │            │  │           │  │ JWT Auth   │  │         │  Log         │
│  │ Decision:  │  │           │  └────────────┘  │         │  Analytics   │
│  │ allow/deny │  │           │                  │         │              │
│  └─────┬──────┘  │           └──────────────────┘         └──────┬───────┘
│        │         │                                               │
│  ┌─────▼──────┐  │           ┌──────────────────┐               │
│  │ Citadel    ├──┼──────────►│  Event Hub /      │───────────────┘
│  │ Audit      │  │  events   │  App Insights     │
│  │ Exporter   │  │           └──────────────────┘
│  └────────────┘  │
└──────────────────┘

1. Agent action triggers AGT policy evaluation (sub-millisecond, in-process)
2. If allowed, the request passes through the Citadel APIM gateway
3. APIM enforces gateway-level policies (rate limit, content filter, JWT)
4. AGT audit exporter sends governance events to Azure Event Hub / App Insights
5. Events include correlation IDs linking AGT decision to APIM request trace

Policy Bundle Binding¶

Citadel Access Contracts use .bicepparam files to declare what resources an agent environment can access. AGT extends this with a policy bundle reference:

// In the Access Contract .bicepparam file
param agtPolicyBundle object = {
  bundleId: 'customer-support-v2'
  version: '1.3.0'
  source: 'https://vault.azure.net/secrets/agt-policy-bundle'
}

At deployment time, the policy bundle is fetched and injected into the agent environment. The AGT runtime loads it at startup via PolicyBundleResolver.

Coverage Boundaries¶

Understanding what each system handles avoids duplication:

Failure Modes¶

Entra Identity Federation¶

The EntraIdentityBridge maps AGT agent identities to Entra ID agent identities for Citadel Layer 3 correlation. This is attestation/federation, not write-back:

• Entra remains authoritative for enterprise identity and lifecycle
• AGT remains authoritative for runtime credentials and trust scores
• AGT trust scores surface as risk labels in telemetry, not Entra metadata

from agent_os.integrations.citadel import EntraIdentityBridge

bridge = EntraIdentityBridge.from_env()

# Bind AGT agent to its Entra managed identity (one-time setup)
binding = bridge.bind(
    agt_agent_id="customer-support-agent-01",
    agt_public_key="<base64-ed25519-pubkey>",
    entra_object_id="00000000-0000-0000-0000-000000000001",
)

# Produce attestation (emitted as telemetry)
attestation = bridge.attest(binding, trust_score=850)
# attestation.risk_label == TrustRiskLabel.TRUSTED

Trust score thresholds: - >= 700: trusted - >= 400: degraded - < 400: untrusted

APIM Governance Metadata¶

The APIM policy fragment (agt-governance-metadata) enables the Citadel gateway to log AGT governance posture without adding AGT to the request hot path:

1. Agent runtime sets X-AGT-* headers before making LLM calls
2. APIM fragment reads headers, logs them as custom trace dimensions
3. Fragment strips AGT headers before forwarding to backend (defense in depth)
4. Response includes X-AGT-APIM-Request-Id for cross-system correlation

See examples/citadel-governed-agent/apim-policies/ for the fragment XML, sample product policy, and deployment instructions.

Getting Started¶

1. Deploy Citadel Governance Hub: Follow the Citadel quickstart
2. Install AGT: pip install agent-governance-toolkit[full]
3. Configure the exporter: Set CITADEL_EVENTHUB_CONNECTION_STRING and CITADEL_APPINSIGHTS_CONNECTION_STRING
4. Deploy the APIM fragment: See apim-policies/README.md
5. See the example: examples/citadel-governed-agent/

References¶

• Foundry Citadel Platform: Full 4-layer architecture
• Citadel Governance Hub: Layer 1 reference implementation
• Citadel Access Contracts: Contract-based onboarding
• Agent 365 / Entra Agent Governance: Layer 3
• AGT Architecture: AGT system design