This is the fourth deep-dive in the system of intelligence series. The first three covered memory, retrieval, and tools and actions. This post is about the layer that wraps all of them.

A model writes confident answers and calls tools with plausible arguments. A model never says “I don’t know.” None of that becomes a reliable production system on its own. The discipline that turns a model into a working agent is harness engineering which is everything wrapped around the model that makes its behavior predictable, auditable, and safe.

The refund that wasn’t

A few months back, I sat in on a triage call for a customer-support agent we’d built on a small model, a cheap, fast, good enough for the routine queries that make up most of the volume. A customer had asked for a refund on a duplicate charge. The agent confirmed the policy applied, called the refund API, got a 200 OK back, and told the customer: “Your refund of $147 has been processed. You should see it in your account within 3-5 business days.”

Except it hadn’t been processed. The 200 response meant the API had received the request. The actual body contained status: "pending_review", the amount exceeded a threshold that required a human approver. The agent saw 200 OK, assumed success, and confidently promised the customer something that wasn’t true.

The customer waited five business days. Nothing happened. They called back angry. Now we had a refund problem and a trust problem.

The temptation was to fix the prompt. Always check the response body. Use exact wording from the API. Don’t say “processed” unless status is “completed.” The prompt got longer. The agent got more cautious. And then it still got things wrong, just in different ways.

The actual fix had nothing to do with the prompt. We layered four harness pieces around the same model:

1. Output schema validation: On the refund tool’s response. The schema declared that status had to be one of ["completed", "pending_review", "denied"], and the harness forced the agent to acknowledge which value it received.
2. A status-to-language map: Only "completed" allowed “your refund has been processed.” "pending_review" mapped to specific language about review being underway. The agent could not improvise customer-facing phrasing on this path.
3. A post-action ledger verifier: Before any success message went to the customer, a separate read against the accounting ledger had to confirm funds had actually moved. No ledger entry, no success message.
4. An incident hook: If any of the above checks failed, the case routed to a senior rep before the customer heard anything.

After the harness landed, the same small model handled refunds reliably. No prompt changes. The model’s “intelligence” hadn’t improved. What improved was everything around it, bounded responses, schema-enforced status mapping, post-action verification, and an escalation path when uncertainty showed up.

That experience crystallized the discipline for me: the model is rarely the bottleneck, the systems around it are. Cheap small model + good harness reliably beats expensive large model + bad harness.

The formula Mitchell Hashimoto coined captures it:

Agent = Model + Harness

The model is the brain. The harness is everything else, the body that gives the brain hands, eyes, reflexes, and a sense of when to stop.

What a harness actually contains

A useful operational definition: if you’re not the model, you’re the harness. Anything in the running agent system that isn’t the model itself which includes, code, config, prompts, hooks, tool descriptions, infrastructure, storage is part of the harness.

That includes the persistent storage substrates the agent reads from and writes to. The context graph from the memory deep-dive is a harness primitive. So are the document store and the vector index sitting next to it and every retrieval flows through them, every memory write lands in them, every audit traces back to them. In a coding-agent harness, this role is played by the filesystem and git; in an enterprise CX harness it’s the context graph, the document corpus, rules on tools and the structured knowledge base.

With that framing, every modern harness has four runtime components. Different teams use different vocabulary, but the architecture is consistent across the literature.

1. Guides (what to do): Feedforward instructions that steer the agent before it acts. System prompts, constraint documents, agent-readable specifications like CLAUDE.md or AGENTS.md, Skill.md. Guides direct the model toward the right behavior in the first place.
2. Sensors (what just happened): Feedback checks that verify behavior after the model acts (or as it acts). Schema validators, output parsers, evaluators, hooks that fire on tool calls, drift detectors. Sensors catch mistakes before they propagate.
3. Guardrails (what’s forbidden): Hard boundaries the agent cannot cross. Permission systems, rate limits, dangerous-command blockers, scope restrictions. Guardrails fail closed: when in doubt, deny.
4. Observability (what did happen): Telemetry, tracing, audit logs, decision-trace persistence. Observability turns the agent from a black box into a system whose behavior can be reviewed.

The refund example from the opening used all four: the schema validator and ledger verifier are sensors, the status-to-language map and incident hook are guides and guardrails, the case logging is observability. No prompt changes. All four pieces sit outside the model, where they can be tested, versioned, and audited as software.

Where harness rules actually live

Production harnesses are mostly composed of:

• Specification files are .md files that the agent reads.
  • AGENTS.md / CLAUDE.md at the repo root describe the project’s conventions, dangerous commands, file-modification rules, and the team’s authoring norms. The agent loads these into context at session start.
  • Per-domain .md files like DEPLOYMENT.md or BANKING_POLICY.md get loaded conditionally when the agent’s task touches that area.

• Hooks files — programmatic interceptors around tool calls.
  • PreToolUse hooks fire before any tool executes. They run schema validation, permission checks, idempotency checks, range checks, rate limits.
  • PostToolUse hooks fire after a tool returns. They run output validation, ledger checks, side-effect verification.
  • Hooks are typically authored as small functions in a hooks.py or hooks.ts file and registered with the runtime.

Skill definitions, SKILL.md files (the Anthropic Skills pattern) that bundle tool definitions with usage instructions. These are guides + tool definitions in one artifact, loaded on demand.

MCP servers, the programs that expose tools and resources to the agent through a typed protocol, enforcing access controls and logging at the protocol layer.

Evaluation suites, test runners that replay decision traces against the current harness rules to catch regressions before they ship.

Build order matters

Teams that succeed with an enterprise CX agent harness don’t build everything at once. A practical sequence:

1. Organizational context first which is the authored surface from the construction-harness section. Before any agent runs, before any tool is registered.
2. Core guides, the AGENTS.md, domain policy .md files, tool descriptions. Once you have a concrete use case.
3. Write-tool harness hooks which are schema validations, permissions, idempotency, policy pre-hooks for the first few high-stakes tools.
4. Workflow tools that encapsulates recurring atomic sequences once a clear pattern emerges in production traces.
5. MCP servers and external integrations because they expose surfaces that need the harness layers above to be solid first.

Each layer builds on the previous one. Teams that try to start at layer 4 or 5 without the lower layers find that their workflow tools fire against an unreliable substrate and their MCP integrations expose tools the harness can’t gate properly.

The amux harness guide puts the rule for what belongs in these files cleanly: “Every line in your AGENTS.md should trace to a real agent failure. If you can’t point to the specific mistake that prompted the line, delete it.” This applies to every piece of the harness. Each rule, hook, and constraint exists because the agent did the wrong thing at least once.

Harness during memory substrate construction

So far we’ve talked about harness at runtime, what fires during a live conversation, while the agent is acting. But there is an entire harness discipline that runs before any agent ever sees the substrate: the gates around how content enters storage and how it becomes part of the context graph in the first place.

Two layers, in the order they fire:

Layer 1 (Pre-ingestion): what earns a place in storage

Before any document, policy, transcript, or organizational fact becomes part of the agent’s substrate, something has to decide whether it belongs there at all. This is the layer most teams skip entirely. They dump every PDF, every wiki page, every meeting transcript into a vector index and call it knowledge. The result is a substrate full of duplicates, outdated drafts, marketing language, and content nobody ever queries.

Pre-ingestion produces records that have passed the entry gate but have not yet been transformed into graph nodes. Content can also enter directly into trusted knowledge when a known authority is the source (a compliance officer publishing a policy, a PM authoring a workflow definition). Both entry paths run through the pre-ingestion gates; trusted entry skips only the discovery gates, not the validation gates.

A pre-ingestion harness asks four things of every candidate source:

• Is it the canonical version? A CRM has nine versions of the late-fee policy. One is current. The harness selects the canonical version (by version field, by publication date, by author authority) and rejects the rest as superseded. A :SUPERSEDED_BY edge keeps the lineage queryable.
• Is anyone actually asking about this? An operational signal which topics customers ask about, which retrievals return zero results, which conversations escalate because the agent couldn’t find an answer . A document about a discontinued product line with zero query volume earns a deprioritized tier or no place at all.
• Does it carry mandatory metadata? Author, last-reviewed date, owning team, sensitivity classification, retention policy. A document without these fields is rejected at the gate, not silently ingested with null everywhere.
• Is the structure parsable? A scanned PDF that OCR can’t reliably extract from is queued for human structuring rather than ingested as garbage. The harness has a quality floor for what it will accept.

Sources break into three categories. Each contributes to different parts of the eventual graph and runs through slightly different gates:

• Structured systems of record: Documents or urls, CRM, billing, HRIS, ticketing. The pipeline knows their schemas and runs deterministic transforms into POLE+O entities. Mostly contributes to the object graph (customers, accounts, products, transactions).
• External tool feeds: Calendar systems, identity providers, organization charts in HRIS, vendor management systems. These contribute primarily to the people and organizational graph (employees, roles, reporting relationships, vendor relationships, departments).
• Authored organizational context: This category deserves its own treatment, because it is the place most teams underinvest in.

Organizational context as a first-class authored surface

The context graph cannot be built entirely from structured sources. Some of the most important content — what does this organization actually do, what are its products, what are its services, who are its customers, what is its tone, what are its non-negotiables exists nowhere as a structured record. It lives in people’s heads, in scattered docs, in onboarding decks. If the agent can’t see it, the agent can’t use it.

A serious construction harness creates a dedicated authored surface for organizational context — a structured folder inside trusted storage where humans write about the organization itself. Not a wiki dump. A structured authoring surface with a fixed template and a review path. Something like:

/trusted_knowledge
  /organization
    overview.md              # mission, business model, scale
    products.md              # product catalog with structured fields
    services.md              # service offerings with SLAs
    customer_segments.md     # who we serve, tier definitions
    tone_and_voice.md        # communication norms, what NOT to say
    /policies
      escalation.md
      authorization_limits.md
      regulatory_constraints.md
    /people
      org_chart.md           # human-authored, syncs with HRIS
      decision_authorities.md

Every file in this surface is authored to a schema and should carry the same mandatory metadata as any other trusted source — author, last-reviewed, owning team. Every change goes through review. The construction pipeline parses these files into the object graph (products, services, segments) and the organizational graph (people, roles, decision authority), enriching what comes in from the structured systems.

The harness rules around this surface are unusual because the surface is itself part of the harness:

• Schema-required authoring: Every product entry has the same fields, every policy entry has the same structure. The author can’t dump prose; the template enforces consistency.
• Mandatory owner: Every file has a named human owner. No orphans.
• Review cadence: last_reviewed more than 90 days ago triggers an alert.
• Change propagation: Updates to organizational context cascade into the object and organizational graphs through the normal construction pipeline.

Layer 2 (Construction): from trusted knowledge to context graph

Once a candidate is in the trusted knowledge , the construction harness governs the transformation into context graph nodes and edges. Five gates fire on every construction pass:

• Schema gates on extraction: Every CRM record, every parsed PDF, every authored markdown file maps into POLE+O types through declared transformations. If a source starts emitting a new field, the schema gate flags an unknown property rather than silently dropping it or guessing where it belongs.
• Entity resolution gates. When the pipeline thinks Salesforce’s “Maria Lopez” matches FIS’s customer 4421 matches the transcript speaker “Maria,” that’s a probabilistic call. Three modes: auto-merge above 0.95, queue for review between 0.7 and 0.95, reject below the floor. Bad merges are nearly impossible to unwind, so the harness errs toward queueing.
• Provenance enforcement: Every node and every edge carries source, confidence, extracted_at, and (for inferred relationships) the extractor version. No provenance, no entry.
• Ontology drift detection: Daily reconciliation against the current POLE+O schema. Nodes flagged by drift get queued for re-classification, never auto-rewritten.
• Batch validation suites: Sample-and-diff against a golden reference before any backfill lands. Fail the batch if the diff exceeds tolerance.

This is the layer that determines whether your graph is a useful retrieval substrate or a quietly poisoned one. The same five gates fire whether the input is a CRM sync, an HRIS feed, or an authored organizational-context file — different sources, one validation discipline.

The metagraph’s typed-edge traversal patterns play the same harness role for retrieval — they replace fuzzy text search with symbol-precise reads (“walk HAS_TIER then HAS_EVENT to :WaiverEvent nodes”) and dramatically tighten the retrieval surface against irrelevant matches. The discipline differs by domain; the architectural function is the same.

Where all this lives in code

/ingestion
  /pre_gates                    # Layer 1
    canonical_selector.py
    query_volume_signal.py      # what people ask about
    metadata_required_check.py
    structure_quality_check.py
  /raw_store                    # staging area between layers
  /trusted_knowledge            # authored content lives here too
    /organization               # the authored surface
  /pipelines                    # Layer 2
    crm_sync.py
    document_extractor.py
    org_context_parser.py
    hris_feed.py
  /gates                        # Layer 2 — same five gates for all inputs
    schema_validator.py
    entity_resolver.py
    provenance_check.py
    ontology_drift_detector.py
  /validation
    golden_set/
    batch_validator.py
  /review_queue                 # human approval, used by both layers

The same principle that governs runtime harness governs construction: every gate is deterministic, every rule traces to a real past failure (a bad merge, a stale doc that misled the agent, an organizational fact nobody had written down). The construction harness is upstream of every retrieval and every decision; getting it wrong propagates everywhere.

One easy diagnostic: if your team can’t answer “where did this graph node come from and what’s its provenance?” in under thirty seconds, your construction harness has holes. The authored-organizational-context surface is the cheapest insurance against the “the agent doesn’t know what we know” failure mode.

A note on what’s missing

The substrate doesn’t stop changing once construction has run. Live conversations produce signals worth folding back in. Decision traces surface patterns that suggest new workflow tools. Slack and Teams threads contain conventions the agent doesn’t know yet. Conflicts between trusted facts surface over time. All of that, the continuous-improvement discipline that turns a static substrate into a learning one is the subject of the fifth pillar, The Learning Loop. The construction harness is what makes today’s substrate trustworthy. The learning loop is what makes it better next week.

Maria’s case, end to end — harness at every step

Theoretical harness rules are easier to follow when you watch them fire in sequence against a real case. Let’s walk Maria’s $39 late fee dispute from utterance to closed ticket and call out exactly which harness rules trigger at each beat. By the end we will have catalogued every harness check the system actually ran during her case.

Step 1 – Utterance arrives

Maria says: “I want to dispute this $39 late fee on my Platinum card.”

Before the agent ever sees that utterance, two harness layers fire:

• Input sanitizer (sensor): The utterance is scanned for prompt-injection patterns, suspicious unicode, and obvious abuse. Pass.
• Session guardrail: Maria’s session token is validated against the auth service. Janet, the senior support rep handling the call, is confirmed as the invoking principal. Without a valid session, the agent doesn’t see the utterance at all.

Step 2 – Tool selection

The agent reads its available tool descriptions and reasons over Maria’s request. late_fee_dispute_workflow is a strong match.

• Scope guardrail: Some tools are restricted by role. The harness checks that Janet’s role permits visibility of this workflow tool. A basic-tier rep wouldn’t even see the workflow tool in the catalog. Pass.
• Selection observability: The agent’s tool choice, including the alternatives it considered is logged. Six months from now, “why did the agent pick this tool?” is a queryable question.

Step 3 – Workflow tool invocation

The agent invokes late_fee_dispute_workflow with a single tool call.

• Schema validation (sensor): The arguments like customer ID, fee event ID, idempotency key match the workflow tool’s declared schema. Pass.
• Idempotency check. The key LFD-CUST_4421-EVT_88291 has not been seen before. If it had been, the harness would short-circuit the call and return the prior result, preventing double execution. Pass.
• Workflow-level permission check (guardrail): Janet has the fee_waiver_initiate permission. Pass.
• Time-out check: The overall tool should be within 5000ms.

Step 4 – Memory writes during and after execution

As the workflow runs, each :TraceStep write passes through the five memory-write gates from the memory post: schema validation, provenance tagging, conflict detection, deduplication, and PII classification. Maria’s $39 transaction passes cleanly; had her SSN appeared in the trace, the PII gate would have routed it to a secured store with only a reference token in the graph.

When the case closes, a single :DecisionTrace is written linking all the trace steps to the outcome. The same five gates fire on that write.

Step 5 – Customer-facing response

The workflow completed cleanly. The agent drafts: “Maria, I’ve waived the $39 late fee on your Platinum card. The reversal should appear on your account within 24 hours.” Three sensors fire before this goes to her:

• Groundedness check: Every factual claim, “$39 fee,” “Platinum card,” “within 24 hours” traces back to retrieved evidence or confirmed tool outputs. Pass.
• Status-to-language guardrail: waive_fee returned status: "completed", so the phrasing “I’ve waived” is permitted. Had the status been pending_review, this phrasing would have been blocked.
• PII redaction: Account numbers, full last names, internal transaction IDs and none slipped into the customer-facing text.

The response ships. The case closes.

A useful tally

The model made one judgment call: which workflow tool to pick. The harness made twenty.

This is what Agent = Model + Harness looks like in operation.

Battling context rot and runaway loops

One harness discipline worth calling out separately: managing the agent’s working context as a case grows. Models degrade as their context window fills — slower to reason, more likely to lose earlier instructions, more likely to confabulate. Production teams call this context rot, and a serious harness has to defend against it.

Three patterns matter in practice:

• Compaction: When the context window approaches its limit, the harness summarizes earlier turns into a compressed form and continues with the summary plus recent turns. Without compaction, long cases either error out at the API boundary or quietly degrade in quality.
• Tool-call offloading: Some tools return large payloads — a 50-chunk retrieval result, a long ledger query, a transcript. The harness keeps the head and tail in context and offloads the full payload to persistent storage; the agent fetches it back only if needed.
• Progressive disclosure: Not every tool description belongs in the context window at every turn. The Anthropic Skills pattern loads only the SKILL.md front-matter on session start; full instructions and bundled tools load on demand when a task matches. Same idea applies to policy documents, traversal patterns, and rule sets — load what’s relevant for the current case, leave the rest available but unloaded.
• Loop discipline. Even with tight tools and clean context, agents can spin. A serious harness sets explicit boundaries on iteration:
  • Iteration caps — a hard maximum on reasoning-tool-call cycles before the case forces termination and routes to a human.
  • Convergence criteria — explicit conditions that tell the agent it’s done (workflow completed, customer confirmed, all subtasks resolved). Without these, the agent keeps “trying to help.”
  • Retry budgets — per tool, the maximum number of times a failed call can be re-attempted. After the budget is exhausted, the harness escalates rather than letting the agent retry indefinitely.
  • Stall detection — if the agent’s reasoning trace stops adding new information across N steps, the harness intervenes. A loop that keeps re-reading the same memory and proposing the same tool is a stall, not progress.

For most enterprise CX cases that resolve in seconds, context rot is a minor concern. For longer-running cases — multi-day disputes, batch reconciliation, multi-product workflows — it becomes a primary harness concern.

When the harness fails

When the agent does the wrong thing, the question is which harness component failed?

• Agent didn’t know a rule → add it to AGENTS.md or a domain .md file (guide gap)
• Agent knew the rule but violated it anyway → add a hook to enforce it (sensor gap)
• Agent lacked information → add a skill, an MCP server, or a retrieval pattern (context gap)
• Agent used a dangerous tool → restrict permissions, add a confirmation gate (guardrail gap)
• Agent’s context got polluted with stale or irrelevant content → use a subagent for isolation, or invoke compaction earlier (orchestration gap)
• Agent crashed and nobody noticed → add observability and alerting (telemetry gap)
• Agent ran in circles → add iteration caps, retry budgets, or convergence criteria (loop gap)

This diagnostic framing turns harness engineering into normal software engineering. Every production incident becomes a debuggable failure with a clear remediation path.

Closing

Three takeaways for the Harness Engineering pillar:

1. Agent = Model + Harness: Most production reliability lives in the harness, not the model. Cheap small model with a good harness reliably beats expensive large model with a bad harness.
2. Every harness rule traces to a real failure: Zero aspirational guidance, zero just-in-case guardrails. Each line in AGENTS.md, each pre-tool-use hook, each post-write check exists because the agent did the wrong thing at least once. The harness grows by accretion, never by speculation.
3. Guides and sensors are both necessary: Guides reduce the probability of mistakes; sensors catch the mistakes that slip through. A harness without sensors is hope; a harness without guides is friction. Real systems balance both, with observability across the top.

The fifth and final pillar is The Learning Loop — how the system uses the decision traces, the QA corrections, and the harness incident log to improve over time. The harness catches today’s mistakes. The learning loop turns yesterday’s mistakes into tomorrow’s training data, guide entries, and workflow tools.