Reference Architecture

Executive summary

ContextOS is the governed decision runtime for production AI agents. It does not try to make a model deterministic. It makes the system around the model deterministic where production systems need determinism: context selection, model invocation, provider routing, tool exposure, policy enforcement, approval routing, trace propagation, evidence capture, decision records, replay, and improvement promotion.

The architecture decomposes the runtime into five planes:

The model sits inside this architecture. It is not the architecture. Model calls cross the AI Gateway / LLM Router; external effects still cross the Tool Gateway.

The same plane boundaries also define the improvement surface. Autotune and reviewer agents may search over harness variants, but only within the fields each plane declares tunable:

This is why improvement is a control-plane concern, not a model-side feature. A candidate can be generated automatically; promotion is still a governed release.

What this architecture is for

This reference is written for platform teams building or evaluating a ContextOS runtime. It answers six questions:

This page is not a tutorial. For a step-by-step MVP, start with Quickstart. For one request end-to-end, read How It Works.

Architectural thesis

Most failed agent architectures collapse four concerns into one prompt: context, reasoning, tools, and governance. That works for demos and fails in production because the organization cannot answer:

• Which facts did the agent rely on?
• Which policies were evaluated?
• Which tools were exposed, and why?
• Which human or system identity authorized the action?
• What exactly would happen if we replay the run?
• Which change caused a regression?

ContextOS separates those concerns into typed planes and turns every important boundary into a contract.

High-level architecture

                         TRUST PLANE
 Policy Engine | Identity | Approvals | Evaluators | OTEL | Replay | Improvement
--------------------------------------------------------------------------------
                         ACTION PLANE
       Tool Gateway | MCP | A2A | OpenAPI | custom adapters | idempotency
--------------------------------------------------------------------------------
                         DECISION PLANE
       Planner | Executor | Critic | AI Gateway | LLM Router | sessions | Decision Catalog
--------------------------------------------------------------------------------
                         CONTEXT PLANE
       Context Pack | Compiler | token budgets | manifests | runtime controls
--------------------------------------------------------------------------------
                       INTELLIGENCE PLANE
       Ontology | Identity Layer | Knowledge Graph | GraphRAG | Memory Fabric

The planes are stacked by dependency direction. Higher planes may constrain lower-plane behavior; lower planes must not bypass higher-plane controls. For example, an adapter cannot self-authorize a destructive action, and a Planner cannot introduce a tool that the Compiler did not surface.

The three ledgers

A production agent run should leave three ledgers. If any ledger is missing, the run is not auditable.

The DecisionRecord indexes all three. It is the durable audit artifact, not a decorative log line.

Core invariants

These invariants are more important than any individual component implementation.

Cross-cutting contracts

RunContext
  run_id
  trace_id
  session_id
  tenant_id
  user.delegation
  agent.workload_identity
  intent
  locale
  safety_mode
  run_budget
 
RunBudget
  total_tokens
  bucket_tokens{business,policy,tool,evidence,memory,session}
  max_tool_calls
  max_replan_attempts
  wall_clock_ms
  max_cost_cents
  atomic_usage{tokens,tool_calls,latency_ms,cost_cents}
 
ApprovalMode
  read_only | local_write | network | delegated | destructive
 
ContextPack
  contract_meta
  pack_meta
  intelligence_refs
  business_context
  policy_layer
  tooling_layer
  decision_layer
  memory_layer
  evaluation_layer
  tone_and_comms
 
CompiledContext
  compiled_prompt
  manifests{policy,tool,evidence}
  runtime_controls{must_refuse,must_escalate,approval_gates_active,redaction_rules_active}
  budget_report
  context_ledger
 
ToolEnvelope
  ToolCallEnvelope{tool_call_id,run_id,capability_id,args,trace_id,idempotency_key,evidence_refs}
  ToolResultEnvelope{tool_call_id,capability_id,status,output,error,citations,mutations,policy_decision_id,latency_ms}
 
DecisionRecord
  record_id
  decision_key
  decision_version
  status
  actor
  subject_ids
  outputs
  evidence_refs
  policy_decisions
  approvals
  controls_active
  budget_usage
  trace_id
  replay_id

Contracts move across planes. Components do not reach into each other’s private state.

Canonical execution contract

invokeAgent(request_envelope, run_context)
  -> resolve pack refs, tenant, identity, intent, safety mode
  -> compile(packs, request, run_context) -> CompiledContext
  -> bind DecisionSpec
  -> route model judgment through AI Gateway / LLM Router
  -> loop {
       planner(CompiledContext)         -> Plan
       critic.verify(Plan)              -> ok | replan | reject | escalate
       executor(Plan, ToolGateway)      -> step_results + evidence_refs
       critic.score(step_results)       -> accept | retry | replan | escalate
       consolidate(effects, evidence)   -> memory_proposals
     }
  -> emit DecisionRecord
  -> emit replay packet and scorecard

Every component is either a participant in this loop, a registry consulted by a participant, or an operator surface over the artifacts the loop emits.

Runtime topology

ContextOS separates authoring and control concerns from hot-path execution.

Deployment rule

Do not deploy the Compiler, AI Gateway, Tool Gateway, and Policy Engine as optional libraries inside agent code. They are platform services or platform-controlled modules because they enforce the boundary. Agent code may call them; it must not replace them.

Tool Gateway names the Action-plane pattern. Tool Manager is the concrete component implementation.

Plane responsibilities

Intelligence plane

The Intelligence plane owns durable meaning. It turns enterprise data into stable identities, typed relationships, evidence refs, and memory that can be safely reused.

Owns:

• canonical entity identity,
• evidence provenance,
• knowledge snapshots,
• memory promotion state.

Does not own:

• deciding which facts enter a specific prompt,
• authorizing external actions,
• final decision outcomes.

Context plane

The Context plane owns per-request compilation. It converts a pinned Context Pack plus RunContext into a CompiledContext envelope.

Owns:

• policy/tool/evidence manifests,
• prompt assembly,
• context budget accounting,
• truncation visibility.

Does not own:

• live tool execution,
• approval decisions,
• memory promotion.

Decision plane

The Decision plane owns the bounded loop. It turns CompiledContext into a plan, verifies it, executes approved steps, scores the result, and emits a typed decision.

Owns:

• plan structure,
• Critic verdicts,
• loop control,
• terminal DecisionRecord emission.

Does not own:

• direct API calls,
• policy truth,
• graph mutation.

Action plane

The Action plane owns external effects. It converts tool intents into validated, authorized, traced calls.

Owns:

• schema validation for tool args and results,
• credential exchange,
• tool transcript capture,
• side-effect idempotency.

Does not own:

• deciding that a risky action is allowed,
• inventing capabilities outside the registry,
• storing final business decisions.

Trust plane

The Trust plane owns control over the other four planes. It makes the runtime governable.

Owns:

• policy decisions,
• approval state,
• scorecards and release gates,
• trace and replay requirements,
• promotion of improvement proposals.

Does not own:

• arbitrary business logic hidden in prompts,
• unreviewed automatic self-modification.

Plane dependency rules

Reference flow: support refund

The refund workflow is the reference example because it exercises all production boundaries:

1. User request enters with a RunContext.
2. Context Pack ctxpack.support@x.y.z and graph snapshot are pinned.
3. Compiler emits CompiledContext with policy, tool, and evidence manifests.
4. Planner proposes lookup, policy eval, and refund steps.
5. Critic verifies tool availability, args, approval mode, and required evidence.
6. Tool Gateway executes read tools and freezes evidence for the risky write.
7. Approval gate authorizes or denies the destructive refund.
8. Executor calls the payment adapter with idempotency key and trace context.
9. Critic scores the completed run.
10. Runtime emits DecisionRecord, replay packet, and memory proposals.

For the complete transcript, see Workflow Examples and How It Works.

Trust architecture

Tenant boundary
  storage, graph, memory, pack registry, traces, and tool credentials are tenant scoped
 
Identity boundary
  user delegation and agent workload identity are both present on every governed call
 
Policy boundary
  policy decisions are evaluated before compile exposure and before tool execution
 
Approval boundary
  network, delegated, and destructive actions can freeze evidence and wait for an approver
 
Audit boundary
  policy decisions, approvals, tool transcripts, scorecards, and traces bind to one trace_id
 
Replay boundary
  request, pack, policy, graph snapshot, model profile, route decision, tool transcripts, evaluator set, and model config are pinned

See Security and Compliance for the detailed control map.

Failure semantics

Failures must be typed. Silent fallback is a production bug.

Observability and AgentOps

Every production run should be observable at four levels.

Recommended span attributes:

contextos.run_id
contextos.session_id
contextos.tenant_id
contextos.intent
contextos.context_pack_ref
contextos.policy_bundle_ids
contextos.approval_mode_required
contextos.approval_mode_effective
contextos.decision_key
contextos.decision_record_id
contextos.replay_id

Tail sampling should force retention for runs that cross approval gates, fail evaluator thresholds, produce incidents, or affect durable business state.

Standards alignment

ContextOS uses existing standards where they fit and adds only the agent-runtime contracts those standards do not define.

Alignment does not mean delegation. MCP or OpenAPI can describe a tool. ContextOS still decides whether that tool is exposed, whether it can execute, which identity it uses, which evidence it must cite, and how the action is replayed.

Control-plane lifecycle

Multi-tenant isolation

Tenant isolation is not only a database filter. It applies to every artifact:

Reference contracts

Implementation checklist

For a new tenant or workflow, do not call the runtime production-ready until every row is true.

Anti-patterns

Roadmap notes

• Plane primitives are stable contracts; individual services may evolve.
• New patterns should be validated against working systems before promotion into this reference.
• Major changes follow the same change-control process as Context Packs, policy bundles, DecisionSpecs, and evaluator sets.

Appendix A: Component inventory

Appendix B: Naming conventions

• Planes: Intelligence, Context, Decision, Action, Trust.
• Primitives: PascalCase (RunContext, ContextPack, CompiledContext, DecisionRecord, ToolEnvelope).
• Enum values: snake_case (read_only, local_write, network, delegated, destructive).
• Identifiers: <scope>:<type>:<id> when human-readable (order:ord_881, customer:cus_77).
• Trace attributes: contextos.<plane>.<attribute> when plane-specific; contextos.run_id and contextos.decision_record_id when global.
• Version refs: <artifact_id>@<semver> for Context Packs, policy bundles, evaluator sets, and DecisionSpecs.