Agentic Context Engineering

Agentic Context Engineering is the discipline of deciding what the model is allowed to see for a specific run, then making that decision reproducible.

It is not prompt writing. A prompt is one output of the Context plane. The real artifact is the CompiledContext: a proof-carrying materialized view containing the bounded prompt plus the manifests, controls, conflicts, omissions, source versions, and budget report that explain how it was produced.

Definition

Agentic Context Engineering turns a versioned Context Pack, a RunContext, and runtime evidence into a CompiledContext envelope.

The envelope must answer four questions:

If those artifacts are missing, the system may still be using good prompts, but it is not doing ContextOS-grade context engineering.

The stronger model: a materialized epistemic view

The compiler does not merely select relevant tokens. It materializes the run’s current epistemic state: which claims are supported, which requirements remain open, which sources disagree, which evidence was superseded by an explicit resolution, and which material was omitted. “Epistemic” here means evidence and uncertainty state; it does not mean hidden chain-of-thought.

This framing adds three obligations to relevance:

1. Sufficiency: the admitted context contains enough current, verified evidence to close every required decision obligation.
2. Consistency: an unresolved conflict on required evidence keeps the obligation open even when both conflicting items are individually current and verified.
3. Lineage: the compiled view preserves the source and resolution references needed to invalidate, replay, or challenge it later.

The view is materialized because the same pinned inputs deterministically produce the same envelope. It is proof-carrying because commit_allowed is derived from explicit gate evidence rather than from the model’s confidence. It is still bounded and lossy: omissions and unresolved state must therefore remain part of the artifact, not disappear during packing.

Why It Exists

Enterprise agents fail when context assembly is informal:

• Policy is copied into prompts and quietly goes stale.
• Tool availability is implied rather than bound to identity and approval mode.
• Retrieval injects evidence without provenance, freshness, access scope, or conflict state.
• Memory writes return as future context before consent or promotion.
• Token pressure silently drops the facts needed for an auditable decision.

The Context plane makes context assembly explicit. It lets the Decision plane reason over a known input envelope and lets the Trust plane replay the run later.

Compiler Contract

The Context Pack Compiler follows the same eight-stage shape used in How It Works:

The compiler may use model assistance for classification, summarization, or compression, but the final envelope must still be typed, versioned, and traceable.

Context Buckets

ContextOS uses buckets so teams can reason about pressure and governance consistently.

Working state that only belongs to the current turn should remain session state. Durable recall belongs in memory only after the Memory Model promotion rules allow it.

Context integrity model

Every material ContextBlock carries ContextProvenance. This is an execution boundary, not decorative metadata:

Integrity and confidentiality answer different questions. Data classification governs who may see a block; integrity governs whether the block may justify an action.

Retrieved evidence is eligible to satisfy a DecisionSpec only when it is admitted, verified, current, and not blocked by an unresolved conflict. stale, unknown, untrusted, budget-omitted, conflict-blocked, and resolution-superseded candidates remain visible in the gate diagnostics but cannot make commit_allowed true. Legacy string-only evidence therefore fails closed until a caller supplies the structured fields.

An EvidenceConflictMarker names the conflicting evidence refs and affected requirements. An unresolved marker makes the gate insufficient; the model cannot settle it by choosing whichever passage sounds more plausible. A resolved marker must carry a resolution_ref and the selected evidence refs, leaving the rejected branch visible for audit and replay.

Evaluated prompt contract

The prompt material inside a CompiledContext is released as an evaluated contract, not edited as free-form prose. A production prompt contract declares:

1. objective — the task and terminal success condition;
2. input trust labels — which blocks are control, verified data, or untrusted data;
3. authority — what the model may decide versus only propose or escalate;
4. decision procedure — required checks, ordering, and evidence gates;
5. tool contract — surfaced capabilities, argument rules, effect boundaries, and required receipts;
6. output schema — the response or decision envelope that must validate; and
7. failure and stopping behavior — what to do when evidence, authority, budget, or progress is insufficient.

The corresponding prompt release record pins the model route, prompt and skill refs, tool/schema versions, stable prefix and cache topology, evaluation datasets and graders, release thresholds, and rollback target. This record contributes to the harness release manifest; it does not replace the canonical CompiledContext or DecisionRecord.

Prompt structure is also a latency control. Stable authoritative prefixes should be separated from volatile evidence and session blocks so caches remain valid without freezing stale state. Routing, prefix-cache hit rate, time-to-first-token, compilation latency, and required-evidence retention are evaluated together; a cheaper prompt that drops a gate-closing fact is a regression.

CompiledContext Shape

The implementation guide owns the full schema. This abridged example shows the integrity-critical fields:

{
  "compiled_prompt": {
    "context_blocks": [
      {
        "block_id": "ev_order",
        "bucket": "evidence",
        "content": "{\"order_id\":\"ord_881\",\"status\":\"delivered\"}",
        "priority": 60,
        "provenance": {
          "source_refs": ["kg:order:ord_881#snapshot_2026_07_31"],
          "origin": "retrieval",
          "integrity": "verified",
          "freshness": "current",
          "instruction_treatment": "data_only",
          "inclusion_reason": "retrieved evidence admitted for support.refund",
          "content_hash": "sha256:..."
        }
      }
    ]
  },
  "manifests": {
    "policy_manifest": [
      { "bundle_id": "POLICY_RETURNS_V4", "rule_ids": ["R_HIGH_VALUE_REQUIRES_APPROVAL"] }
    ],
    "tool_manifest": [
      { "adapter_id": "adp_orders", "capabilities": ["lookup"] }
    ],
    "evidence_manifest": [
      {
        "evidence_ref": "kg:order:ord_881#snapshot_2026_07_31",
        "source_id": "orders-db",
        "hash": "sha256:...",
        "integrity": "verified",
        "freshness": "current",
        "instruction_treatment": "data_only",
        "satisfies": ["order_lookup"]
      }
    ]
  },
  "runtime_controls": {
    "approval_gates_active": ["GATE_FINANCE_APPROVAL"],
    "must_refuse": [],
    "must_escalate": ["fraud_signal_high"],
    "redaction_rules_active": [],
    "context_admission": {
      "data_only_block_ids": ["ev_order"],
      "untrusted_block_ids": [],
      "privileged_sink_policy": "verified_or_user_intent"
    },
    "evidence_gates": [
      {
        "decision_key": "support.refund.execute",
        "required": ["identity_verified", "order_lookup", "policy.eval"],
        "satisfied": ["identity_verified", "order_lookup", "policy.eval"],
        "unresolved": [],
        "rejected_evidence": [],
        "conflicts": [],
        "sufficiency": "sufficient",
        "commit_allowed": true
      }
    ]
  },
  "budget_report": {
    "tokens_used_at_compile": 620,
    "omissions": [],
    "warnings": []
  },
  "context_ledger": {
    "pack_ref": "ctxpack.support@1.0.0",
    "evidence_refs": ["kg:order:ord_881#snapshot_2026_07_31"],
    "omissions": [],
    "compiled_context_hash": "sha256:..."
  }
}

Quality Signals

Context quality is not a vibe. The compiler should emit signals that can be scored later:

These signals feed Evaluation and Observability and the Improvement Loop. They should be stored as diagnostics, not hidden in logs.

Autotune surfaces

The Context plane is the safest first place to apply autotune because many changes are bounded, replayable, and reversible. A Context Pack may declare tunable surfaces, but the compiler must refuse proposals outside that declaration.

Every candidate should produce a TuningProposal that names the target intent, target metric, baseline pack, replay sets, expected scorecard delta, and rollback target. The Context plane does not promote the candidate; the Trust plane gates it through replay, review, and staged rollout.

Boundary With Adjacent Pages

Agentic Context Engineering is the discipline. The Context Pack Compiler is the component. The Context Pack is the source artifact. CompiledContext is the runtime artifact.

Failure Modes

Operational Metrics

• Context compile latency by stage.
• Required evidence coverage.
• Evidence-gate closure rate by decision key.
• Untrusted-evidence admission rate (target: zero for satisfying evidence).
• Stale and unknown-freshness rejection rate.
• Required-evidence conflict rate, resolution rate, and time to resolution.
• False-closure rate: decisions marked sufficient despite a known unresolved conflict (target: zero).
• Legacy evidence migration warnings and content-hash mismatch failures.
• Omission rate by bucket and reason.
• Tool manifest eligibility mismatch rate.
• Policy manifest evaluation error rate.
• Replay match rate for CompiledContext reconstruction.
• Prompt-contract schema pass rate and stable-prefix cache hit rate.
• Recall reconstruction correctness across source, memory, evidence, policy, and authority changes.
• Budget pressure by intent and pack version.
• Decision quality delta after context-pack changes.

Example

For support.refund, the compiler should include:

• the active refund policy bundle,
• the eligible read and refund tools,
• order and customer evidence refs,
• the support.refund.execute decision binding,
• GATE_FINANCE_APPROVAL when the amount exceeds INR 3000,
• a budget report showing whether any evidence or session state was compressed.

The Planner can then propose work against a known envelope. The Critic can reject a plan if required context is missing before the refund tool is ever called.

Common Misconceptions

• “Better prompts solve context.” Better prompts help, but governance comes from typed inputs, manifests, and replay.
• “Retrieval is the Context plane.” Retrieval is one input. The Context plane also resolves policy, tools, memory, budgets, and controls.
• “Two verified sources mean the context is stronger.” If they disagree on a required claim, the context is insufficient until the conflict is explicitly resolved.
• “Summaries are always safe compression.” Summaries must carry source refs, transformation metadata, and quality signals.
• “The model can decide which policy matters.” Policy selection and enforcement happen outside model discretion.

Related Docs

• Context Pack
• Cognitive Core
• Knowledge Graph
• Memory Model
• Evaluation and Observability