How It Works

This page walks one request through ContextOS end-to-end, naming every primitive that touches it and every artifact that comes out. The example is support.refund because it exercises every plane: retrieval, policy, identity, approval-mode binding, decision typing, and audit.

Core promise

A request enters the runtime carrying a RunContext. The Compiler assembles a bounded CompiledContext from the pinned Context Pack. The bounded Planner / Executor / Critic triad runs the cognitive loop. Every side effect routes through the Tool Gateway under the declared approval-mode tier. The output is a typed DecisionRecord with evidence, approvals, controls, and a trace.

The canonical contract (recap)

invokeAgent(request_envelope, run_context)
  → compile(packs, request, run_context) → CompiledContext
  → loop {
       planner(CompiledContext)         → Plan
       critic.verify(Plan)              → ok | replan | reject
       executor(Plan, ToolGateway)      → step_results, evidence
       critic.score(step_results)       → accept | retry | replan | escalate
       consolidate(effects, evidence)   → memory_proposals
     }
  → DecisionRecord(evidence_refs, approvals, controls_active, trace_id)

Step 1 — Receive the request

The caller sends an invokeAgent envelope with a RunContext. See API Contracts for the full shape. The minimum:

{
  "request_id": "req_9f3a12",
  "session_id": "sess_42f1",
  "tenant_id": "tenant_acme_prod",
  "user": { "user_id": "usr_771", "delegation": { "auth_type": "oauth2", "scopes": ["orders.read", "payments.refund"] } },
  "agent": { "agent_id": "agt_support", "workload_identity": "spiffe://contextos/agents/support" },
  "context_pack_refs": ["ctxpack.support@5.2.0"],
  "input": {
    "intent": "support.refund",
    "message": "Refund order ord_881 for INR 4200.",
    "context": { "identity_verified": true, "order_id": "ord_881", "refund_amount": 4200, "currency": "INR" }
  },
  "mode": "stream",
  "runtime": { "plan_timeout_ms": 15000, "max_tool_calls": 8, "max_payload_bytes": 1048576 },
  "trace": { "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", "span_id": "00f067aa0ba902b7", "trace_flags": "01" }
}

The runtime materializes a RunContext (run_id, the trace IDs, safety_mode, run_budget) and pins the Context Pack version + Knowledge Graph snapshot for replay.

Step 2 — Compile the Context Pack

The Context Pack Compiler runs its eight stages:

1. Intent classification — resolve support.refund to its template in the Intent-Task Catalog.
2. Policy resolution — evaluate JsonLogic rules from the pack’s POLICY_RETURNS_V4 bundle against the Run Context.
3. Tool surfacing — intersect Registry ∩ Permissions − Prohibitions; apply approval-mode filter.
4. Evidence retrieval — query the Knowledge Graph under hop budgets.
5. Memory recall — pull promoted memory only.
6. Token budget allocation — distribute run_budget.bucket_tokens across context buckets.
7. Bucket assembly — pack each bucket to its budget; truncate by priority, never silently.
8. Manifests + runtime controls — emit compiled_prompt, policy_manifest, tool_manifest, evidence_manifest, runtime_controls.

The output is a CompiledContext envelope. See Agentic Context Engineering for the discipline; see Context Pack for the schema.

Step 3 — Plan

The Planner reads the CompiledContext and produces a typed Plan:

{
  "plan_id": "plan_refund_01",
  "intent": "support.refund",
  "steps": [
    { "id": "s1", "tool": "adp_orders.lookup", "params": { "order_id": "ord_881" }, "approval_mode": "read_only" },
    { "id": "s2", "tool": "adp_policy.eval", "depends_on": ["s1"], "approval_mode": "read_only" },
    { "id": "s3", "tool": "adp_payments.issue_refund",
      "depends_on": ["s2"],
      "approval_mode": "destructive",
      "requires": ["GATE_FINANCE_APPROVAL"] }
  ],
  "decision_checkpoints": [
    { "decision_id": "support.refund.execute", "after_step": "s2" }
  ]
}

The Planner cannot execute anything; it only proposes the plan.

Step 4 — Critic verifies the plan

The Critic checks:

• every tool exists in the pack’s tool_manifest,
• every argument satisfies its schema,
• the approval_mode declared on each step matches the adapter’s capability binding,
• the decision checkpoint resolves to a Decision Spec with required_evidence the Planner can satisfy,
• the plan does not violate any guardrail in runtime_controls.

A clean verify produces an ok verdict; otherwise control returns to the Planner under the max_replan_attempts budget.

Step 5 — Executor runs the plan

For each step, the Executor calls the Tool Gateway:

• s1 and s2 are read_only; they execute inline.
• At the decision checkpoint after s2, before the destructive refund call, the Critic checks support.refund.execute against its required_evidence (verified identity, order lookup, policy decision).
• s3 is destructive — the Orchestrator routes it through propose → approve → execute: a frozen evidence snapshot is taken, an approver from the role declared on the gate is notified, and only on approve does the call go through.
• Because the request is for INR 4200 by a support_agent, the INR 3000 high-value threshold activates GATE_FINANCE_APPROVAL.

Each ToolCallEnvelope / ToolResultEnvelope pair carries the policy_decision_id, effective approval_mode, evidence refs, mutation refs, idempotency key, and W3C trace context.

Step 6 — Critic scores

After all steps complete, the Critic scores the run on evaluators (Policy / Utility / Latency / Safety / Economics) and renders one of accept / retry / replan / escalate. Acceptance produces the DecisionRecord:

{
  "record_id": "dr_2026_05_04_a17",
  "decision_key": "support.refund.execute",
  "decision_version": "1.0.0",
  "status": "DECIDED",
  "actor": { "type": "AGENT", "id": "agt_support" },
  "outputs": { "refund_amount": 4200, "currency": "INR", "transaction_id": "txn_q9..." },
  "evidence_refs": [
    "kg:order:ord_881#snapshot_kg_2026_05_03_T0930",
    "tool:adp_orders.lookup:tc_117",
    "tool:adp_policy.eval:tc_119",
    "tool:adp_payments.issue_refund:tc_121"
  ],
  "policy_decisions": [{ "policy_decision_id": "pol_9901", "rule_ids": ["R_REFUND_REQUIRES_IDV", "R_HIGH_VALUE_REQUIRES_APPROVAL"] }],
  "approvals": [{
    "gate_id": "GATE_FINANCE_APPROVAL",
    "approver": "user_finance_lead_77",
    "approval_mode_effective": "destructive",
    "evidence_snapshot_hash": "sha256:b2a1..."
  }],
  "controls_active": { "must_refuse": [], "must_escalate": [], "approval_gates_active": ["GATE_FINANCE_APPROVAL"], "redaction_rules_active": [] },
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "budget_usage": { "tokens": 4720, "tool_calls": 4, "cost_usd_cents": 0.91, "wall_clock_ms": 1840 }
}

Step 7 — Consolidate

The Consolidation layer produces memory write proposals (e.g., “customer prefers email updates” with evidence_ref, consent_check: passed). They land in the Memory review queue per the pack’s promotion policy.

Reference architecture

See Reference Architecture for the full reference design.

Inputs and outputs

Inputs

• invokeAgent envelope with RunContext
• Pinned Context Pack + Knowledge Graph snapshot
• Memory state (working / episodic / semantic / durable, post-promotion only)
• Adapter registry with declared approval modes

Outputs

• DecisionRecord with evidence_refs, approvals, controls_active, trace_id
• Tool transcripts and evidence manifest
• Memory write proposals
• OTEL trace bundle and scorecard

Failure modes that block execution

• Policy gate or guardrail not satisfied at the boundary.
• required_evidence for the Decision Spec missing or unresolvable.
• Approval gate unanswered within the gate timeout.
• Tool schema validation fails at the Tool Gateway.
• Loop guard trips on repeated identical tool calls.
• Run Budget exhausted before the plan can complete.

In every case, the failure is a typed verdict the Critic returns, not an unhandled exception.

Where each step is specified

Where to go next

You have now seen one run end-to-end. Pick your next door:

• Build it → Quickstart — model this same support.refund workflow as the smallest governed MVP.
• Run the compiler → Context Pack — change the inputs and watch the CompiledContext (and its deterministic hash) recompile live.
• Go deep → Reference Architecture — the full five-plane reference design.
• Find your path → the Docs Overview has reading paths tailored to platform, product, applied-AI, security, and executive readers.