The conversation around harness engineering is dominated by problems from coding and personal agents such as OpenClaw, but most agents are simpler. Builders should avoid over-engineering for capabilities that newer models may absorb anyway, the “Kirby effect”, and focus on durable fundamentals.
Statisticians sometimes use a deliberately crude question to show how a summary statistic can mislead: how many testicles does the average human have? The numerical answer may be defensible, but it describes almost nobody. Harness engineering has a similar problem. Ask, “What techniques do I need?” and the average answer becomes a long list: context management, memory, compaction, sub-agents, hooks, and orchestration. Few systems need all of it and the right harness depends on the job.
In this essay, you’ll learn:
What an agent harness is and how it differs from prompt and context engineering.
How action complexity and context complexity determine the harness you need.
Why coding and deep-research agents require more context management than many support, sales, and enterprise agents.
How tools, state, routing, guardrails, traces, sub-agents, hooks, and human handoffs fit into the architecture.
Why harness features expire as models improve, and how to build the minimum viable harness for the job.
👉Want to build agents that do more than look good in a demo? Join me live for Build AI Agents from First Principles. You’ll turn a simple LLM call into a working customer-service agent, adding tools, state, context, guardrails, an agent SDK, and MCP as you go. You’ll leave with working code, a reusable architecture, and a clear understanding of how the whole system fits together. Register with code agents10 for 10% off.👈
What is an Agent?
An AI agent in common parlance is an AI system that can do things: send emails, query databases, ping APIs, make appointments, write and execute code, and so on. AI engineers define them slightly differently: AI agents are LLMs with tools in a loop.
Consider what happens when you ask a coding agent to edit a file: it will first read the file, send the result back to the LLM, then edit it, then perhaps read it again, and so on, until the LLM “decides” it is finished and tells you.
This distinction is important because most common parlance agents don’t have such reasoning loops and are more aptly described as LLM workflows: take a sales workflow that
Transcribes sales calls using a speech-to-text model;
Extracts structured data from the transcript for the salesperson to verify;
Populates your CRM or database with the prospect’s information, next steps, and so on.
This is an AI workflow: foundation models are used at each step, but for each sales call the workflow itself is deterministic. A call is transcribed, the relevant data is extracted, and the CRM is populated. When the next call happens, the workflow runs again as a separate task; no result is fed back to an earlier step, so there is no model-directed reasoning loop (any individual step could contain one, however, and agentic reasoning loops inside deterministic workflows are a common pattern).
All modern AI chat products, such as ChatGPT and Claude, however, are agentic: they have access to Web Search tools and image generation tools, for example, and will use them when deemed necessary. You interact with agents every day.
What is an Agent Harness?
If an LLM is the brain, you can think of the agent harness as the body: all the tools and infrastructure it relies upon at runtime to get the job done.
In practice, the harness handles five core jobs:
Loop: Prompt the model, parse its response, execute its tool calls, and feed the results back.
Tool execution: Run the commands, code, APIs, and other actions requested by the model.
Context management: Decide which instructions, conversation history, files, and tool results enter each model call.
State: Track the conversation, task progress, files touched, and anything that needs to persist across turns.
Safety: Sandbox execution, require confirmation for sensitive actions, and block disallowed operations.
Prompt engineering shapes an individual model call. Context engineering determines what the model sees. Harness engineering governs the complete system around those calls.
How Complex Does the Harness Need to Be?
One way to decide how much harness engineering a task requires is to separate two kinds of complexity:
Action complexity: How many tools, decisions, dependencies, and handoffs must the agent coordinate?
Context complexity: How much information must the agent gather, retain, and retrieve to complete the task?
The two can move independently. A support agent may complete a conversation in one turn while still routing across several tools and safety checks. A deep-research agent may receive only one user request while accumulating a large body of source material.
Harnesses for Coding Agents?
The conversation around harness engineering has exploded recently and much of the focus is on context management, memory, compaction, tool offloading, and increasingly elaborate tools and techniques. If you’re building a coding agent (or using one!), it’s important to know about these. Generally, they’re important to consider when building agents that users tend to have long conversations with.
The core can be surprisingly small, though: A coding agent can be built in 131 lines of Python, while a search agent using the same basic loop takes just 61. The tools change, but the underlying pattern doesn’t. A coding agent can even read its own tool definitions, write a new tool, hot-reload it, and use it on the next step. Capabilities can be added without permanently baking everything into the core harness.
A stock coding agent can write code, but it doesn’t automatically understand your data, spot leakage, choose the right validation strategy, explain uncertainty, or connect a model to a business decision. In practice, users keep extending the harness around it: they add domain instructions to AGENTS.md, package recurring workflows as skills, and add tools, evals, and reproducibility checks. The shipped harness is only the starting point. It’s something builders actively work on. In a word, when using a coding agent, you are always actively involved in shaping and building your harness.
So what are common harness patterns for coding agents? Lance Martin (Anthropic, then at LangChain) identified 3 main context engineering patterns, which are fundamental for harness engineering:
Reduce: Actively shrink the context passed to the model
Offload: Move information and complexity out of the prompt.
Isolate: Use multi-agent architectures to delegate token-heavy sub-tasks.
Then when conversations get longer than the context window of the LLM, you need to think through how to pass the necessary context to it: compaction used to be state of the art, then hand-off became prominent, and now compaction is back, due to the capabilities of more powerful models.
Deep research is another case where context engineering matters. In a workshop with Ivan Leo, who previously built agents at Manus and is now at Google DeepMind, we built a deep research agent from scratch. The harness keeps research findings and task state available across many model calls. It generates a plan, gives search sub-agents separate queries and iteration budgets, runs them concurrently, then returns their findings to the main agent for synthesis and citation. The implementation also uses hooks, which let other parts of the system respond to events in the agent loop. A hook can render a tool call, log its result, or record a trace without putting that behavior inside the core loop. Deep research raises both action and context complexity: the agent must coordinate many searches while retaining enough evidence to produce a coherent, cited report.
When working with personal agents, such as OpenClaw or Hermes, managing context and memory is also super important, particularly as the amount of information they create and have access to grows over time. Pi offers a useful baseline for coding-agent harnesses. It adds repository context through AGENTS.md, persistent sessions that users can resume or branch, and extensions for tools, skills, and prompts. OpenClaw builds on Pi and pushes the harness into personal-agent territory with an always-on daemon, chat interfaces, file-based memory, scheduled heartbeats and cron jobs, and tools for browsing, sub-agents, and device control. That additional infrastructure makes sense because the agent must persist and act over time, rather than complete one short task. Its memory system is deliberately plain: compaction summaries are appended to timestamped Markdown files, with no vector database or embeddings.
I do think these are all important and super interesting, but I want to help builders understand that most agents you’ll build don’t need any of them. But first: the Kirby effect and how frontier models are absorbing all of our agent harnesses.
The Kirby Effect
New model releases often force us to rebuild our harnesses. In fact, we often need to tear them out and rebuild them completely. If you don’t rip out your harness, it constrains the new model. As Nick Moy, an AI researcher at Google DeepMind who built the first multi-hop AI agent at Windsurf told me, “we should just unleash [the model], unfetter it, and let it flex its wings!”
Manus has been re-architected five times in a year, LangChain’s Open Deep Research was rebuilt multiple times in a year to keep pace with model improvements, and even Anthropic rips out Claude Code’s agent harness as models improve (see here for more details). Why is this happening? Because the models are sucking up the harnesses around them.
Remember chain-of-thought (CoT) prompting where we would see better performance from LLMs if we asked them to explain their reasoning? Well, it turns out that if you do reinforcement learning on CoT traces, you can build reasoning models! Plan mode followed the same path. AMP briefly shipped it as an experimental feature, then removed it when models could reliably obey “plan, but don’t edit.” As Nicolay Gerold (Amp Code) put it, “Having a separate mode for that, and having additional load on the user to remember, ‘Hey, I always have to go into plan mode,’ isn’t necessary anymore, because it’s just one simple instruction.” Claude Code still has it, though, as does Codex! In November 2025, the release of Opus 4.5 and GPT-5.2 signalled a step change in how capable coding agents had become. Simon Willison even wrote “It genuinely feels to me like GPT-5.2 and Opus 4.5 in November represent an inflection point”. Why was this possible then? The labs had been able to train their new models on enough of our agent traces, in particular using RLVR, that they were able to become far more accurate at tool calling, among other things.
Nicolay Gerold (Amp Code) calls this the Kirby effect: every component in a harness encodes an assumption about something the model cannot do on its own. As models improve, those assumptions expire, and the corresponding harness features can be removed.
Harnesses for Support Agents
Most AI builders will not be building coding agents or deep-research systems. They will be building support agents, sales agents, and enterprise agents that sit low on at least one of these dimensions. Many of these systems complete a task in one to five turns (time to resolution is key here!). Their harnesses still need careful tool design, structured outputs, routing, guardrails, traces, and handoffs, but they may need far less memory and compaction.
William Horton (AI Engineer, Maven Clinic) and his team built Maven Assistant to help members navigate appointments, providers, support information, and women’s health content. When the agent first reached external users, every initial conversation was completed in a single turn. Compaction was rarely relevant, although one Zendesk retrieval returned far too much text. The architecture still contains several important harness components:
Domain routing: A lead agent delegates requests to sub-agents for appointments, provider search, health content, and Maven support.
Bounded tool access: The system has roughly 15 to 20 tools distributed across those domains. Each sub-agent receives only the tools relevant to its job.
Tool interfaces designed for agents: Internal APIs are wrapped in safer interfaces. The application injects the user ID directly instead of asking the model to provide it.
Deterministic guardrails: Off-topic and prompt-hacking checks run before the main agent. When triggered, the system returns a fixed response without asking the LLM to improvise.
Explicit human handoffs: Expressions of self-harm trigger an automatic transfer to support. Other transfers require the user to ask or confirm.
Controlled scope: The agent provides health information but does not diagnose. The team withheld high-cost benefits questions until the system could answer them reliably enough.
Maven Assistant has low context complexity and moderate action complexity. Its harness work is concentrated in routing, tool design, guardrails, evaluation, and human handoffs rather than memory or compaction. But don’t forget about the Kirby effect: as these systems become more sophisticated, so will the models, and what you needed to engineer into your harness yesterday will be part of the model tomorrow.
The fundamentals will remain:
Building LLM reasoning loops with tools, state, and control flow.
Designing prompts and tool schemas.
Managing context and memory.
Using structured outputs, traces, and tool feedback to inspect and debug the loop.
Applying guardrails and human handoffs.
Using Agent SDKs and MCP without outsourcing the system design.
Running scheduled and event-driven work with hooks and cron jobs.
Building evals that test task success, tool use, guardrails, and human handoffs.
Evals also raise a boundary question. Vivek Trivedy’s account of the agent harness is runtime-oriented: it includes the tools, state, context, execution environment, orchestration, and control logic used while an agent completes a task. Hamel Husain has argued to me (in private correspondence) that the eval harness is part of the agent harness too. That extends the definition beyond runtime to include the infrastructure that runs test cases, captures traces and artifacts, and scores outcomes. We’ll discuss this, among other things, in an upcoming live conversation.
When building agents, before reaching for compaction, memory, handoffs, or sub-agents, map the job on two axes: how many actions must the agent coordinate, and how much context must it carry across the task? If both are low, keep the harness small. Give the model the few tools it needs, test the loop, and add infrastructure only when a real failure demands it. Revisit those additions whenever a stronger model arrives, because yesterday’s necessary workaround may be tomorrow’s dead weight.
👉 Want to go deeper? Check out our collection of agent-harness resources, including papers, talks, tools, and practical examples. I’m also running a four-hour workshop soon, Build AI Agents from First Principles, where we’ll build a working customer service agent from scratch and cover tools, state, context, memory, guardrails, SDKs, and MCP. Register with code agents10 for 10% off 👈
How You Can Support Vanishing Gradients
Vanishing Gradients is a podcast, workshop series, blog, and newsletter focused on what you can build with AI right now. Over 70 episodes with expert practitioners from Google DeepMind, Netflix, Stanford, and elsewhere. Hundreds of hours of free, hands-on workshops. All independent, all free.
If you want to help keep it going:
Share this with a builder who’d find it useful
The point that harness features expire as models improve is a sharp reminder not to over-build for today's model.
I built a repo of runnable examples showing minimal harness patterns for different agent jobs, relevant here.
https://github.com/hardness1020/awesome-agent-architecture