FDAI Architecture

FDAI is built from independent agents. Each agent owns one job and talks to the others only through schema-checked events, so the parts that observe, decide, approve, execute, and audit never collapse into a single component. The control plane runs headless, the console stays read-only, fixes arrive as pull requests, and approvals happen in chat.

A fixed organization of 15 agents makes those responsibilities explicit. Each agent owns typed objects and a lifecycle role inside the control plane. Agents add ownership on top of the control loop. They never replace it and never skip its deterministic safety checks.

Azure is the implemented target. Every cloud call goes through a provider contract, so the core never imports an Azure SDK and you can move to another host without rewriting decision logic.

Governed automation flow

Start with the conceptual view when you need to explain how an operator’s natural-language intent becomes a governed action. It separates language understanding, semantic context, policy judgment, action selection, execution, feedback, and durable stores without tying the explanation to Azure resource placement.

The numbered cards show the primary path. The lower surfaces expand the same concepts into shared context, typed semantics, deterministic policy, registered actions, execution targets, measured outcomes, and durable evidence. Use the reference architecture next when you need authority and deployment boundaries.

Reference architecture

Use the reference view to identify system scope, authority boundaries, and governed dependencies before tracing an individual event. The headless control plane contains typed event choreography and the control stages owned by the 15 agents. Model providers, tools, policy and query engines, knowledge, evidence, and the Azure deployment foundation remain outside that inner boundary. The foundation lists AKS as the default runtime and Container Apps as the compatibility profile.

The collective pantheon mark represents the fixed 15-agent organization, not a sixteenth agent. T2 alone uses the quality gate; every tier uses the common safety and authority check. Human approval returns as a typed event instead of calling the executor directly. OPA and Rego evaluate deterministic policy, while IQL performs bounded inventory queries. Use the system overview for one-event flow and the Azure views for deployment and resource-level connections.

Design at a glance

FDAI has five loosely coupled layers. They share typed events, versioned contracts, and Git. They do not share one process or one identity.

The console reads projections from the state and audit stores. It does not use the executor identity, it cannot approve a change, and it never calls an Azure API that changes anything.

Azure deployment topology

Choose the view that matches the deployment runtime. AKS is the default for new installations; Container Apps remains a compatibility profile. The logical control loop and authority boundaries are the same in both.

AKS deployment

This view shows the AKS profile with an authenticated public Console and postgres-flex. Azure Static Web Apps hosts the browser application outside the cluster. Azure API Management (APIM) provides its HTTPS API gateway and routes Operator requests and /ingestion requests to separate AKS services.

Read the diagram from left to right: authenticated access, the AKS runtime, then Azure data and operational services. Shared workload dependencies sit below the main flow. The API boundary excludes scheduled jobs, and the Event Hubs connection represents shared service transport, not a Core-only bus.

• Service placement: Five independent Deployments run the Core Control Plane, Operator Service, Document Ingestion API, Document Processing Worker, and isolated Executor. The Worker includes a ClamAV sidecar. Scheduled work runs as CronJobs, not Container Apps Jobs.
• API access: Externally exposed APIs use Kubernetes LoadBalancer Services; other services use ClusterIP. The API services validate Entra tokens. APIM is the browser gateway, not the Kubernetes management API.
• Identity and images: Namespaced ServiceAccounts federate through AKS Workload Identity to separate managed identities. Key Vault supplies service-specific secret references through the CSI driver. Container Registry supplies digest-pinned images. Only the isolated Executor is eligible to hold approved resource-effect roles; runtime selection does not enable execution.
• Data and events: Event Hubs carries schema-validated service events; there are no direct agent-to-agent calls. PostgreSQL uses service-owned roles, and Azure Storage holds documents and history. Group-level connections summarize these paths, not shared credentials or unrestricted data access. The common-dependency and operations areas list supporting services without repeating every identity, image, model, approval, and telemetry connection. Azure products use their product icons; Kubernetes Deployments, nodes, and CronJobs use their corresponding Kubernetes icons.
• Network scope: AKS uses an application VNet, a node subnet, and a delegated API-server subnet with API Server VNet Integration. The basic profile restricts public management access by CIDR and Entra RBAC. Private cluster access, service private endpoints, peering, and private DNS depend on the selected networking profile; this picture does not assert they are enabled.

The diagram describes reusable deployment configuration, not a tenant inventory or live health report. Model access, approval channels, and diagnostic collection need their own configuration and verification. The optional postgres-aks profile places PostgreSQL inside AKS and is not depicted here. See runtime deployment profiles for placement and readiness requirements.

Container Apps deployment

Container Apps remains a compatibility profile with the same five services, control loop, and authority boundaries. The resource network flow in the next section is its deployment view. It shows the five services in a VNet-integrated Container Apps environment, the private-endpoint paths to Azure services, and the delivery channels.

The view maps the parameterized Terraform deployment, not one tenant’s resource names. Azure OpenAI and some private endpoints remain optional. Human App Roles and the privileged executor managed identity stay separate in every profile.

Azure resource network flow

This is the Container Apps private-network reference, not the AKS profile above.

Use this view to trace current and target-state connections at the Azure resource level. It separates the private Application Gateway, Container Apps infrastructure, and private endpoint subnets, then maps each private endpoint to its managed service backend. The diagram shows the FDAI Web Console path. The FDAI CLI uses the same Operator API but is omitted from this view for clarity.

The baseline portion shows the default private-networking profile, where enable_private_postgres=false adds a postgresqlServer private endpoint. Setting enable_private_postgres=true replaces that path with PostgreSQL Flexible Server in its delegated subnet and doesn’t create the endpoint. The document path separates its authenticated Ingestion API from the durable Processing Worker. Both use the optional Blob and DFS private endpoints and ADLS Gen2 account. One Event Hubs symbol represents both the primary and operational namespaces because they use the same Azure resource and private-link pattern. Case-history storage is documented but not repeated as another Storage Account and private-endpoint pair. The development operations gateway and APIM remain in their feature-specific profiles.

The same view overlays the intended gateway, model platform, observability, and delivery-provider topology. Elements that Terraform does not provision are drawn with dashed outlines and a “(planned)” label. The table below states the status of each target-state element.

Target-state element	Terraform status	Documentation decision
Private Application Gateway subnet with Application Gateway and WAF policy	Not provisioned	Keep in the diagram as planned topology; add its Terraform profile before treating the path as deployable
Microsoft Foundry account, project, and private endpoint	Opt-in feature profile	Keep in the diagram; availability depends on LLM and web-search settings
Azure Managed Grafana	Not provisioned	Keep in the diagram as planned observability topology
Email, Teams, and Slack approval channels	Email is opt-in; Teams and Slack are deployment adapters	Keep as provider choices; each deployment selects credentials, callback identity, and fallback policy
GitHub, GitLab, and Azure DevOps delivery providers	Deployment adapters	Keep as provider choices; each deployment selects the Git host and review bindings

The diagram does not need every Terraform resource as a separate node. Use the following inclusion rule: draw a resource when it changes a network boundary, creates a distinct data path, or is a user-visible delivery endpoint. Group or document resources that only support those paths.

Terraform resource or resource group	Diagram treatment	Reason
Operational Event Hubs namespace and its private endpoint	Aggregate under Event Hubs	It uses the same Event Hubs and private-link symbols; the node description covers primary and operational topics
Case-history Blob account and its private endpoint	Keep documented	It uses the same Storage Account and Blob private-endpoint symbols, so repeating the pair adds clutter without a new interaction pattern
Container Apps environment	Keep aggregated	The Container Apps subnet boundary and app/job nodes already communicate its hosting role
Private DNS zones and VNet links	Keep implicit in private-endpoint paths	Drawing each zone and link would duplicate every private endpoint without changing the workload flow
Action group, metric alerts, and diagnostic settings	Keep aggregated under App Insights and Logs	These resources implement observability routing rather than a separate workload data path
Event Grid realtime inventory topic	Exclude from this private profile	Terraform enables it only when private networking is disabled

No extra nodes are required for these resources. They and the other supporting resources remain intentional abstractions rather than missing architecture.

Azure Resource Graph reads and observability writes are shown outside the private data-plane path because they use Azure control-plane and telemetry contracts. This Container Apps reference still doesn’t add an Application Gateway, WAF, Managed Grafana, or load balancer.

The validated five-service baseline and one candidate

The 15 agents are logical responsibility owners inside the Core runtime. They are not 15 Azure services. FDAI retains five independently releasable services, each with its own image, Terraform state, migration branch, health contract, and workload identity. SD-10 adds a separately packaged System Knowledge Service candidate that remains undeployed until its graduation evidence exists.

Service	Responsibility	Effect authority
Core Control Plane	Agent runtime, decisioning, approval joins, audit intent, and recovery coordination	None
Operator Service	Authenticated queries, conversations, projections, and governed request submission	None
Document Ingestion API	Authenticated upload intake and API-owned document transitions	None
Document Processing Worker	Durable inspection, extraction, indexing, claims, and reconciliation	None
Isolated Executor	Command validation, target locking, provider effect, rollback attempt, and execution receipt	Sole eligible holder
System Knowledge Service candidate	Release-bound FDAI reference search and a dedicated Teams mention bot	None

The event bus and versioned service contracts connect the validated baseline. The candidate uses its own catalog, Teams HTTPS ingress, and service contract. No service imports another service’s implementation or shares mutable workflow state.

The five architecture layers

Layer	Responsibility	Primary boundary
Headless control plane	Normalize events, pick a trust tier, verify proposals, classify risk, and coordinate execution	No UI logic and no direct cloud SDK imports
Action delivery	Turn approved actions into fix pull requests or registered provider calls	Every action keeps its typed safety contract and rollback reference
Operator console	Show state, evidence, audit history, observation-mode results, and pending approvals	Read-only identity with no permission to execute
Human channel	Deliver approval requests and operational alerts through ChatOps	The approver is never the executor
Rule catalog	Keep rules, policies, action types, prompts, and promotion evidence versioned as code	Catalog changes go through review, regression tests, and observation-mode evaluation

These layers fail and scale independently. If the console goes down, event processing keeps running. If ChatOps goes down, high-risk work waits in a queue instead of executing without approval.

How one event moves through the system

Every event takes the same path, whether it comes from an Azure resource change, an SLO burn detector, a scheduled job, or an operator request.

The system overview under Design at a glance draws this path.

1. Ingest and correlate: FDAI checks the event schema, drops repeats using a stable idempotency key (a key that makes a retry safe), and groups related signals into one incident.
2. Pick the lowest tier that can decide: T0 (deterministic rules) handles the repeatable majority, T1 (lightweight reuse of similar past incidents) handles known patterns, and T2 (grounded LLM reasoning) handles only the new or ambiguous cases.
3. Verify before you classify risk: a T2 proposal has to pass mixed-model agreement, an evidence check, and schema, policy, security, and what-if checks. A plausible answer is not enough.
4. Apply the autonomy ceiling: the safety check weighs action risk, impact scope, system health, and policy. It answers auto, approval required, or deny.
5. Execute once, record every path: the executor takes a per-resource lock, applies an action that is safe to retry, and writes the result. Rejections, timeouts, holds, rollbacks, and no-ops are audited the same way.

Read Deterministic first for the tier boundaries and Trust tiers for the autonomy decision.

The agent organization inside the control plane

FDAI’s 15 named agents are an ownership layer over the control loop. They are not 15 separate Azure services, and they are not chatbots making free-form decisions. Each agent is a runtime object with one mandate, a set of object types it owns, the topics it subscribes to, and bounded permissions.

All agents run inside the same Python control-plane process and talk through an injected event bus. Sharing a process does not soften the boundaries: an agent still publishes only what it owns. If you later split them into separate processes, the topics and the authority model stay the same.

How the 15 roles fit together

Architecture function	Agents	Ownership in the control loop
Sense and observe	Huginn, Heimdall	Huginn owns normalized events and real-time resource discovery ingress. Heimdall owns anomaly, drift, and forecast detected issues.
Judge and arbitrate	Forseti, Odin	Forseti issues decisions. Odin resolves cross-vertical conflicts before Forseti finalizes a decision.
Execute, approve, recover, and explain	Thor, Var, Vidar, Bragi	Thor is the sole privileged executor. Var carries human approval. Vidar owns rollback. Bragi translates operator conversations.
Govern evidence and knowledge	Saga, Mimir, Norns, Muninn	Saga owns append-only audit. Mimir owns rules. Norns proposes inert learning candidates. Muninn owns state snapshots and context indexes.
Supply domain evidence	Njord, Freyr, Loki	Cost, capacity, and chaos specialists advise judgment. They never execute.

The 15 roles are fixed upstream, so a fork cannot merge two conflicting roles or rename an authority boundary. A fork can bind providers, tune thresholds, turn off optional agents, and add catalog entries. Saga and Vidar are hard dependencies, so you cannot turn off audit or rollback.

Runtime data flow

The table above is the organization chart. The diagram below is the data flow: which agent-owned object moves where.

The interactive view shows the topology at runtime: agents subscribe independently, work can fan out in parallel, and only the owning agent publishes each authoritative object. Gateways and workers relay events. They never become hidden decision makers.

The flow follows one simple rule: information can fan out to many readers, but each authoritative object type has exactly one writer. Many agents can read a decision, for example, and only Forseti can publish object.verdict. The publish-side registry checks that ownership. If a record declares a producer that does not match the topic owner, the event-bus bridge sends it to the dead letter queue. Records with no declared producer are reported separately so the boundary can be tightened. Knowing a topic name is not the same as holding authority over it.

Single-writer topic ownership

Single-writer ownership turns an agent role into something the runtime can enforce, not just something the docs describe.

Object or topic	Single writer	Architectural effect
Event / object.event	Huginn	A cloud adapter cannot pretend to be normalized control-plane ingress.
Verdict / object.verdict	Forseti	Specialists and models can advise, but they cannot make an action eligible to run.
ArbitrationDecision	Odin	Cross-vertical trade-offs have one deterministic tie-breaker.
ActionRun / object.action-run	Thor	Only the executor can claim an attempted change and report how it ended.
Approval / object.approval	Var	The executor cannot fabricate its own approval.
Rollback / object.rollback	Vidar	Recovery stays a separate path you can test on its own.
AuditEntry / object.audit-entry	Saga	Final evidence has one append-only owner.
RuleCandidate / object.rule-candidate	Norns	Learning proposes inactive data and cannot edit the catalog directly.
Rule and Policy	Mimir	Turning a rule on or off stays a governed catalog operation.

Agent modules never import one another to call a handler directly. They publish the objects they own and subscribe to the topics they declared, so the runtime wiring always matches the table above.

ActionType role binding

Every registered ActionType ties the action lifecycle to named agents:

initiator -> Forseti (judge) -> Thor (executor) -> Var (approver when required)
                                            -> Saga (auditor on every terminal path)
                                            -> Vidar (compensation when required)

The initiator changes from action to action. The judge, executor, approver, and auditor roles are fixed upstream. The binding also carries the rollback contract, the irreversibility flag, and the compensating action. That is what stops a fork from letting a domain specialist approve its own work, or from naming the component that made the change as its own auditor.

Two ports, one authority path

Every agent exposes two ports:

• Typed pub/sub port: the authoritative machine path. It uses registered topics, schema-checked payloads, producer verification, and the deterministic-first control loop.
• Conversational port: a bounded natural-language path for operator questions and agent-to-agent lookups. Bragi routes the question and writes the answer. Bragi never judges and never executes.

The two ports share only the correlation trace. If you ask Bragi to perform an action, Bragi builds a typed proposal and sends it through Huginn, so the request goes through validation, judgment, risk, approval, execution, and audit like any other event. A conversation can explain authority. It cannot become authority.

Runtime placement and promotion

The runtime starts the agent organization beside the established control-loop consumer and measures the two against each other.

Current implementation status: The agents start with the control plane and run in observation mode, where they judge and log but apply no changes. Named ownership describes the authority contract. It does not mean every agent is cleared to make live changes. Enforcement mode stays blocked until every durable safety binding is in place.

• Shared ingress, separate consumers: both paths read the same Kafka topic under different consumer groups, so the agents observe events instead of taking them away from the established loop.
• Observation mode by default: Thor records what the agents would have done but cannot change anything, so nothing executes twice while you compare the two paths. Set FDAI_START_PANTHEON=0 only when you need to stop the agent runtime for maintenance.
• Enforcement is a separate promotion: starting in enforcement mode requires a live Thor executor, durable action-run storage, a durable Saga audit chain, registered Vidar rollback executors, and a deployment-level authority ceiling in the startup readiness report. If any one is missing, startup stops.
• Failure isolation: the agent runtime is watched separately. If it fails, the failure is reported and the established event consumer keeps running.

This layout lets you compare stage-level and agent-owned outcomes before you move execution authority. The architecture stays stable while the implementation is promoted step by step.

Trust and authority boundaries

In FDAI, separation of authority is an architecture property. It is not a user interface convention that a later change can quietly undo.

Boundary	Why it exists	Enforced behavior
Judgment vs execution	Whoever proposes or judges a change should not apply it	Forseti judges, and Thor executes the accepted typed action
Approval vs execution	A privileged executor cannot approve its own work	Var carries approval through a separately authorized channel
Console vs control plane	A browser session should not hold permission to change anything	The console reads projections and evidence only
Model proposal vs eligibility	A plausible model answer is not evidence	Deterministic verification decides whether a T2 proposal may proceed
Observation vs enforcement	A new capability should prove itself before it changes anything	New actions observe and audit first, and enforcement is promoted separately
Replay vs re-execution	Investigating an incident should not repeat a production change	Audit replay rebuilds the judgment without running the action again

The agent organization assigns these roles to named agents, and no agent may skip the typed control loop. A request that arrives through a conversation re-enters the same event, verification, risk, and audit path as any other request.

Code and data boundaries

The repository follows the same dependency direction as the runtime system.

• core/ holds decision and coordination logic. It depends on shared contracts, never on Azure SDKs or UI components.
• shared/ defines versioned event, action, rule, workflow, and provider contracts. It never imports the core.
• delivery/ implements persistence, Azure access, GitOps, notifications, ChatOps, and Operator APIs behind those contracts.
• rule-catalog/ and policies/ hold governed data. You can add a rule or an action type without rewriting the control loop.
• The composition root reads validated configuration, picks the concrete providers, and injects them at startup.

For the complete dependency map, read Project Structure.

Azure implementation

The first implementation maps each portable contract to a small Azure resource set. Provider-specific calls stay inside adapters, so swapping a resource does not touch decision logic. AKS is the default runtime for new installations, and Container Apps remains a compatibility profile.

Portable concern	Contract	AKS (default)	Container Apps (compatibility)
Event stream	Kafka wire protocol	Event Hubs through its Kafka endpoint	Event Hubs through its Kafka endpoint
Core runtime	OCI image and portable manifest	Kubernetes Deployments in a user node pool	Container Apps
Scheduled work	Job or cron contract	Kubernetes CronJobs	Container Apps Jobs
State, audit, and T1 vectors	PostgreSQL and pgvector	Azure Database for PostgreSQL Flexible Server	Azure Database for PostgreSQL Flexible Server
Secrets	Environment or mounted secret	Key Vault references mounted by the CSI driver	Key Vault reference injected by Container Apps
Workload identity	OIDC token	AKS Workload Identity federated to user-assigned managed identities	User-assigned managed identity
Inventory	Resource graph contract	Azure Resource Graph plus activity deltas	Azure Resource Graph plus activity deltas
Observability	OpenTelemetry-compatible signals	Log Analytics and Application Insights	Log Analytics and Application Insights
Console	Static read-only application	Azure Static Web Apps	Azure Static Web Apps
Console Operator API	HTTP read contract	Operator Service behind API Management	Container App with its own read-only identity
Document ingestion	Upload and chunking contract	Ingestion API and Processing Worker with Data Lake Storage	Container Apps with Data Lake Storage
Human approval	Typed approval message	Teams bot and Adaptive Cards	Teams bot and Adaptive Cards

On AKS, each service sets its own replica floor and ceiling, and the floor is at least one. On Container Apps, the core runs continuously with a floor of one replica and a ceiling of three. That floor stays at one because scale-to-zero needs a credential-free Kafka-lag scale rule, and without that rule an incoming event would never wake the app. Scheduled jobs and static surfaces can still scale to zero. For the full provider surface, read CSP-neutrality contracts.

Safety built into every action

An action type is incomplete until it declares all seven safeguards:

• Stop condition: the measurable signal that halts execution.
• Rollback path: the tested way to restore the old state or move forward safely.
• Impact scope limit: the largest scope, batch size, concurrency, or rate the action may touch.
• Dry-run receipt: the successful what-if result for the exact target and revision.
• Logical-target lock: held until the side effect commits.
• Idempotency key: stable duplicate suppression across retries.
• Two-phase audit: intent before the effect and terminal closure after execution and independent outcome observation.

If a required dependency such as the audit store is unavailable, FDAI drops autonomy to observation mode or holds the work for review. It does not fail open.

Example: configuration drift

Consider a resource change that opens network access wider than policy allows:

1. Azure emits a resource-change event onto the Kafka-compatible event bus.
2. Event ingest normalizes the payload, attaches inventory context, and finds the resource’s correlation key.
3. T0 matches a versioned network rule and proposes a typed fix.
4. What-if confirms the exact diff. The safety check sees that the impact scope needs approval.
5. ChatOps sends an approval card with the rule, the evidence, the impact scope, the stop condition, and the rollback reference.
6. After approval, the executor opens a fix pull request instead of changing the resource from the console.
7. Delivery, approval, and the final outcome are linked in the append-only audit trail, and the console shows them as read-only evidence.

A denial, rejection, timeout, or rollback follows the same path. Only the last step differs.

Failure isolation

Failure	System response
Console unavailable	Core processing, Git delivery, and ChatOps keep running
ChatOps unavailable	Work that needs approval waits in a queue and never auto-executes
Event backlog grows	Backpressure caps concurrency and keeps work for retry or dead-letter handling
Audit or critical provider unavailable	Autonomy drops to observation mode, or the action is held
Duplicate delivery	Idempotency keys and resource locks stop a second change
T2 models disagree	The competing evidence is kept and the case goes to human review
Rollback verification fails	The incident stays open and recovery escalates through the typed pipeline
Forseti unavailable	No new agent decision is issued, and work is held for review
Thor unavailable	Detection, judgment, and audit continue, but nothing changes
Var unavailable	Work that needs approval stays queued, and a timeout becomes an audited no-op
Saga or Vidar unavailable	Enforcement startup and changes are blocked, because audit and rollback are hard dependencies
Agent runtime fails	The failure is logged and the established primary consumer keeps running

Next steps

To learn about	Read
How tiers choose a decision method	Deterministic first
How actions become auto, approval required, or deny	Trust tiers
How typed actions and workflows fit the loop	Agent-driven automation
How the named agents divide responsibility	Agents and self-healing
How Azure resources are prepared safely	Deployment preflight
How operators respond to incidents	SRE runbooks