AI harness

What is an AI harness?

An AI harness is the software layer around a language model that lets it do real work. The model itself receives text and returns text. The harness handles everything around that exchange: calling tools, passing results back to the model, managing context, asking for approval, retrying failures, and deciding when the task is finished.

In simple terms: an agent is a model running inside a harness. Without the harness, the model can answer. With the harness, it can search files, call APIs, run code, update systems, and complete a multi-step task.

The word harness is not a formal standard with one universal definition. It is practical engineering language for the runtime that turns model calls into a working product.

What the harness actually does

A good harness solves the same set of problems, whether it is a coding agent, a customer-support agent, or an internal data assistant.

• The loop. The harness calls the model, receives the model's next action, executes it, returns the result, and repeats until the work is done or a limit is reached.

• Tool integration. It exposes tools to the model: file reads, search, SQL queries, API calls, browser actions, code execution, or workflow steps. It also validates the tool inputs before anything runs.

• Context management. It decides what goes into the context window: system instructions, user messages, retrieved documents, summaries, file snippets, tool results, and memory from earlier steps.

• Permissions. It decides which actions can happen automatically and which need human approval. Reading a file is different from deleting a record or sending an email.

• Stop conditions. It prevents runaway loops by setting limits on steps, time, cost, retries, or tool calls.

• Logging and traceability. It records what the model saw, which tools it called, and what changed. Without this, debugging an agent becomes guesswork.

• Error handling. It turns failed tool calls, empty search results, permission errors, and malformed outputs into something the model or user can recover from.

Harness, framework, and agent

The terms overlap, but they are not identical.

Model
The language model predicts the next response or action based on the input it receives.

Framework
A framework is a toolkit for developers. It may provide tool calling, state graphs, memory, tracing, and deployment helpers. LangGraph, AutoGen, Semantic Kernel, and the OpenAI Agents SDK live in this area.

Harness
The harness is the running wrapper around the model in a specific product or workflow. It may be built with a framework, but it includes the concrete prompts, tools, permissions, logging, limits, and error behaviour.

Agent
The agent is the user-facing system: model plus harness plus tools, aimed at a goal.

This is why the same model can feel sharp in one product and clumsy in another. The difference is often not the model. It is the harness: better tools, better context, better examples, clearer stop rules, and safer permissions.

Examples of harnesses

A coding assistant in the terminal is a clear example. Claude Code and Codex do not just send your question to a model. They inspect files, run commands, keep a task plan, apply patches, ask for approval where needed, and decide when enough verification has run. That surrounding runtime is the harness.

A BI assistant can have a different harness. It may expose only approved semantic models, a SQL runner with read-only access, a charting tool, and a policy that requires a human to approve any scheduled report change.

A customer-service agent has another shape again: knowledge-base search, CRM lookup, draft replies, escalation rules, tone instructions, and a hard stop before refunds or account changes.

The common pattern is the same: the model supplies judgement and language, while the harness supplies the operating environment.

Build your own or use an existing harness?

Using an existing harness gets you started quickly. Vendor products usually handle tool calling, approvals, tracing, authentication, and updates better than a weekend prototype.

Building your own gives more control. You can decide exactly which tools exist, how context is assembled, where logs go, how permissions work, and how the agent fits internal systems. That control comes with maintenance: model changes, API changes, prompt regressions, security reviews, and production support.

A sensible path is to start narrow. Use a simple model call or an existing agent product for the first version. Build a custom harness only when you need behaviour the product cannot provide: a specific permission model, strict audit logs, unusual tools, or tight integration with internal workflows.

What to watch out for

Hidden autonomy
If the harness quietly lets the model take actions, users may think they are only chatting while the system is changing data. Make action boundaries explicit.

Tool descriptions
Models choose tools based on names, descriptions, and examples. Vague tool descriptions produce wrong calls.

Context clutter
More context is not always better. A harness that stuffs every document and every prior message into the prompt can bury the important signal.

Runaway loops
Every agent needs hard limits. A loop with no step cap can keep spending money while making no progress.

Auditability
If the agent touches customer data, finance data, or production systems, log the tool calls and decisions in a way a human can inspect later.