Skip to main content

📝 Harness Engineering

Description​

< What is it? >​

  • [Harness]
    • Agent = Model + Harness
      • Model: the "brain"
      • Harness: the "body", that helps the agent operate safely and reliably, including:
        • Tools: APIs, code execution, search, databases and business applications
        • Memory: Prior context, user preferences and workflow history
        • Workspace: Files, data, environments and systems the agent can access
        • Guardrails: Permissions, policies, approvals and monitoring
    • A harness is everything around the model that turns a text-completion API into a working system: the loop that calls it, the tools it can reach, what goes into its context on each turn, the sandbox it runs in, and the checks that tell you whether any of it works. The model weights are fixed; the harness is the part you actually engineer.
    • The same model can look brilliant or useless depending on its harness. Most production quality problems are harness bugs — a stale tool description, a context window filled with irrelevant history, a tool that returns 40,000 tokens of JSON — not model failures.
  • [Why it is its own discipline]
    • Prompt engineering owns what you say to the model.
    • Agentic AI System owns the decision loop.
    • Harness engineering owns everything the loop runs on: tool schemas, the context lifecycle, permissions, and evaluation. The boundary matters because a "bad answer" has to be attributed to one of the three before it can be fixed.
  • [The agent loop]
    • The irreducible core of every harness: assemble context → call the model → parse tool calls → execute them → append results → repeat until the model stops or a budget is hit. Everything else in this page is a decision about one of those five steps.

< Prompt vs Context vs Harness Engineering >​

DisciplineWhat is focuses onMain artifactTypical applicaitons
Prompt engineeringWording the input to get a better responseA well-crafted promptEarly LLM applications
Context engineeringCurating what information the model sees and whenRetrieval pipelines, memory designRAG-era applications
Harness engineeringDesigning the full system around the model — tools, sandboxes, loops, guardrailsThe harness itselfAgentic systems and autonomous workflows

Key points​

< Tool design >​

  1. [Tools are an API for a reader, not a program] the model picks a tool by reading its description, so the description is the load-bearing part of the schema — it must say what the tool does and when to use it, not merely restate the name. See the tool anatomy on the Agentic AI System page.
  2. [Consolidate, don't enumerate] ten narrow tools that each do one query cost more context and more wrong choices than one tool with a clear parameter. Every tool in the prompt is a permanent tax on every turn.
  3. [Return tokens the model can use] a tool that dumps raw JSON or a 40k-token file burns the context the agent needs for reasoning. Return filtered, summarized, or paginated results, and let the agent ask for more.
  4. [Error messages are prompts] "Error 422" teaches nothing; "file not found — did you mean src/app.ts?" lets the agent self-correct without another round trip.

< Context engineering >​

  1. [Context is a budget, not a bucket] every token spent on stale history is a token unavailable for reasoning, and quality degrades well before the window is technically full.
  2. [Compaction] when the window fills, summarize the older turns and carry the summary forward rather than truncating blindly — truncation silently drops the decision that explains the current state.
  3. [Offload to the file system] write intermediate results to files and keep only the paths in context. The agent re-reads what it needs, when it needs it.
  4. [Sub-agent isolation] delegate token-heavy exploration to a sub-agent that returns only its conclusion — the caller's context never sees the search.
  5. [Caching] a stable prompt prefix (system prompt, tool definitions, then history) lets the provider cache it; a prefix that changes every turn silently forfeits the discount.

< Permissions and sandboxing >​

  1. [Least privilege per tool] read-only tools can run freely; anything that writes, spends, or sends should require an explicit allow rule.
  2. [Confirm the irreversible] deletes, pushes, payments, and outbound messages are the class where a wrong tool call cannot be undone by another tool call.
  3. [Isolate parallel writers] agents editing the same files concurrently corrupt each other's work — give each one a worktree, branch, or scratch directory and merge afterwards.
  4. [Treat tool output as data] text returned by a tool — a web page, a file, another agent's answer — is untrusted input, never instructions to follow. This is the prompt-injection boundary.

< Evaluation and observability >​

  1. [Trace every turn] you cannot debug what you cannot replay. Log the full context, the tool calls, and the returns for each step.
  2. [Eval on outcomes, not vibes] a fixed task set with programmatic success checks turns "it feels better" into a number that survives a prompt change.
  3. [Budgets and termination] token ceilings, step caps, and wall-clock limits are correctness features — an agent left to route freely does not reliably stop.

Architecture​

< What a harness is made of >​

[The six components of the agent harness]​
harness architecture diagram

  • [State and persistence] State and persistence stores and retrieve an agent’s execution context—checkpoints, intermediate outputs, and the agent’s position within a multi-step task. When an agent crashes partway through a run, this layer determines whether it resumes from the last successful step or starts over. State artifacts accumulate quickly in long-running agents and need the same lifecycle management applied to operational data: backup, retention, and access control. They also continue to consume infrastructure while an agent is paused—for instance, waiting on human approval—which is a common source of unexpected cost at scale.

  • [Security and governance] Security and governance controls what an agent is permitted to do, on whose authority it acts, and what record is produced of its actions. It covers identity propagation, permission scoping, and auditability. This is where most enterprise agent projects stall before production. Assurance and compliance teams typically require an industry-standard set of controls for autonomous systems, which for agents does not yet exist; each organization ends up building its own, usually late in the project. The failure modes cluster into three: data exfiltration when scoped identity does not propagate through tool calls; prompt injection when context is not sanitized; and inaccurate access controls when the agent acts under a shared system identity rather than the originating user’s.

  • [Orchestration and tool use] Orchestration and tool use drive the agent loop: when to perceive, plan, act, and which tool to call. Tool use reaches external systems—APIs, databases, search services, and other agents. MCP⁸, introduced by Anthropic in late 2024, solved connectivity: agents can now reach tools through a common interface. It did not solve coordination, access control, rate limiting, or sandboxed execution. Production incidents tend to originate in that gap. A common pattern is an agent that successfully calls a tool, receives a response it was not designed to handle, and loops indefinitely while consuming tokens—the connectivity worked; the surrounding coordination did not.

  • [Memory] Memory has two levels. Agent-side memory is working memory—the context assembled for the current turn. Harness-side memory is the persistent store: a short-term cache plus long-term episodic, conversation, and entity stores, accessed through a vector index. Each turn, the agent reads from the persistent store into working memory; the action layer writes results back. The infrastructure characteristics are volume (schema-free data accumulates fast) and retrieval (quality depends on embedding accuracy and vector search). Memory also connects to a separate problem: enterprise data. Agents that need to reason over existing operational data meet the memory layer at the same entry point.

  • [Observability] Observability records what the agent did, what it decided, what it used, and what happened as a result. It is fundamentally different from application monitoring: the question is not whether the system responded but whether the decision it made was correct. Three signals are essential—the output, the reasoning trace (why the agent chose this path), and the memory fragments and tool calls that contributed to the decision. As of early 2026, no widely accepted AgentOps playbook exists; each team is assembling its own from database observability tools, LLM observability vendors, and custom instrumentation.

  • [Evals] Evals run out-of-band, reading from observability after the fact. They determine whether an agent is ready to deploy and whether it should remain deployed. An eval suite consists of test cases, success criteria, and the infrastructure to run those tests repeatedly over time. The difficulty is that deterministic success criteria do not map cleanly onto non-deterministic systems. A production agent has to work reliably across many runs, not pass once. As of early 2026, there is no widely accepted eval framework for agent quality; the measurement problem is ahead of the tooling.

[The relationship between agents, harnesses, and platforms]​
harness platform diagram
  • [The platform layer] The six harness components sit on top of a second layer the current discourse rarely names: the platform. Where a harness manages one agent system as one coordinated runtime, the platform provides the infrastructure that makes many harnesses operable across many teams over time. It has four properties. Durable execution keeps an agent’s work intact through process crashes and long pauses, so the harness can resume from a checkpoint instead of starting over. Governance propagates identity and produces audit evidence automatically, so the harness does not have to reimplement it per deployment. Cost visibility surfaces spend at the agent and action level, not aggregated across a team, so budgets stay traceable. Data integration reaches enterprise systems without requiring migration, so the harness’s memory layer can hit the data that already exists.

< Standard interfaces >​

  • MCP (Model Context Protocol) — an open protocol for exposing tools, resources, and prompts to any model host, so a tool server is written once instead of per application.
  • Provider tool-use APIs — the native function/tool-calling format each model exposes; the harness translates its registry into whichever one it is targeting.

Crash course​

Reference​