A coding model can suggest a patch. A coding agent must carry that patch through a real repository, execute tools, absorb failures, preserve task state, and return evidence a human can review.
That difference is architectural. The model supplies probabilistic reasoning; the agent is the whole system that turns reasoning into bounded, observable software work.
The model is the reasoning engine
The ReAct pattern established a crucial loop: reasoning selects an action, the environment returns an observation, and the next decision changes. A coding agent specializes that loop for software engineering, where the environment is not one API. It is a repository, filesystem, shell, dependency graph, test suite, application runtime, version-control history, and sometimes a browser or deployment platform.
The model remains important. It interprets intent, forms hypotheses, proposes edits, chooses tools, and updates a plan. A stronger model may navigate ambiguity better or recover from a surprising result with fewer attempts. But it does not directly own the filesystem, process isolation, credentials, persistent threads, or the truth of a test result.
That boundary is visible in OpenAI’s description of the Codex agent loop: the harness orchestrates the interaction among user, model, and tools. The later Codex App Server architecture adds thread persistence, configuration, authentication, sandboxed tool execution, extensions, and a bidirectional protocol for events and approvals. Those are not prompt details. They are runtime responsibilities.
| Responsibility | Model contribution | Agent-system contribution |
|---|---|---|
| Understand | Interpret intent | Retrieve current, attributable context |
| Act | Propose a next move | Validate, authorize, and execute it |
| Continue | Update the plan | Persist task state and observations |
| Finish | State a conclusion | Verify behavior and preserve evidence |
Context is an interface, not a pile of tokens
A coding agent needs a way to enter an unfamiliar codebase. It must locate relevant files, understand local conventions, discover commands, distinguish generated code from source, and find the architectural constraint that applies to this change.
Dumping the repository into a long prompt is neither scalable nor reliable. Useful context is progressive: a compact map points to domain documentation; search retrieves a narrow slice; nearby tests show expected behavior; version history explains why a strange constraint exists. Context also needs provenance. The agent should know whether a rule came from current code, a committed instruction, generated output, or an assumption.
OpenAI’s harness engineering case study describes repository knowledge as a system of record and argues for giving agents a map rather than a thousand-page manual. The practical lesson is broader than any one product: context engineering is information architecture for a worker that must decide what to inspect next.
A task is longer than one completion
Software work rarely follows a single prompt-to-answer arc. The agent orients itself, forms a plan, edits files, executes a focused check, reads the failure, revises the patch, runs broader verification, and prepares a handoff. Each stage produces state that later stages need.
Persistent state makes that trajectory durable. A thread records the conversation and tool events. A task plan records what remains. The worktree records the current patch. A trace records commands, observations, and approvals. A handoff summarizes what changed and what still needs attention.
This becomes essential when work spans many context windows or sessions. Anthropic’s work on effective harnesses for long-running agents used structured artifacts and incremental progress so a later session could continue from the repository rather than reconstructing everything from memory. The agent does not need perfect recall when the environment preserves legible state.
Tools need an agent-computer interface
Giving a model a shell is not the same as giving it a good software-engineering interface. Commands must be discoverable, outputs bounded, edits precise, and errors informative. A tool should make the correct action easy to express and the result easy to interpret.
The SWE-agent paper, Agent-Computer Interfaces Enable Automated Software Engineering, makes this interface quality explicit. Its agent-computer interface was designed around navigating repositories, viewing and editing files, and executing programs. The insight is analogous to ordinary product design: capability depends on the affordances and feedback of the interface, not just the intelligence of its user.
For coding agents, a good interface exposes narrow search, structured file edits, cancellable commands, clean diffs, stable exit status, browser state the model can inspect, and test failures that point toward a cause. A noisy or ambiguous tool shifts work back into guesswork.
Reliability fails around the model
When an agent produces a bad patch, “the model made a mistake” is too broad to be useful. The same visible failure can begin in several parts of the system.
A context failure sends the agent to the wrong file or hides a current rule. A tool failure accepts an ambiguous action or returns unusable output. A runtime failure introduces dependency drift, missing services, or state another run cannot reproduce. A verification failure declares success because a narrow test passed while the user-visible behavior remained wrong.
This classification changes the remedy. Context failures need better maps and retrieval. Tool failures need sharper schemas and observations. Runtime failures need reproducible environments. Verification failures need checks closer to the real acceptance criteria. Model routing still matters—some work benefits disproportionately from a stronger model—but upgrading the model is not a substitute for repairing a broken interface.
The harness owns operational truth
The model should propose. The harness should enforce.
That means the harness validates tool arguments, applies permissions, chooses the execution boundary, captures changed state, formats observations, maintains budgets, and decides when human approval is required. It also supplies the verification gate that determines whether the requested outcome is supported by evidence.
This separation protects both safety and correctness. A generated command does not receive authority merely because it is fluent. A claim of completion is not evidence merely because it sounds confident. The system can pause a destructive operation, reject an out-of-scope path, distinguish a timeout from a test failure, and require a human decision when taste or organizational context cannot be encoded mechanically.
It also creates a stable place to improve. Teams can refine repository maps, tool contracts, sandboxes, test output, UI inspection, and handoff formats independently of model releases. Those improvements compound across every model and every task.
From coding agent to harness engineering
A coding agent is therefore not “an LLM plus shell access.” It is a stateful software system in which a model reasons inside a designed environment. Its quality depends on whether that environment makes the right context discoverable, the right actions possible, side effects bounded, progress durable, and success verifiable.
This system map gives us the boundary. The next article turns it into an engineering model: six harness layers that teams can inspect, assign ownership to, and improve without treating every failure as a prompt problem.
Sources
- OpenAI — Unrolling the Codex agent loop
- OpenAI — Unlocking the Codex harness
- OpenAI — Harness engineering
- Anthropic — Effective harnesses for long-running agents
- Yang et al. — SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering
