What Is an AI Agent Harness?

A large language model on its own can only do one thing: take text in and give text out. It can't run code, read your files, remember yesterday's session, or check whether its answer is correct.

An AI agent harness is the software that gives it those abilities. It wraps the model, calls it in a loop, runs the tools it asks for, feeds the results back, and decides when the work is done.

A simple way to remember it:

Agent = Model + Harness

When you use Claude Code, Codex CLI, OpenCode or any other AI coding assistant, you're not talking to the raw model. You're talking to a harness that manages the model for you.

The model sits in the middle. Everything around it is the harness.

Why is it called a "harness"?

A harness is the gear that connects a horse to a cart and steers it. The horse provides the power; the harness points that power in a useful direction. An LLM works the same way: the model provides the intelligence, and the harness provides the structure.

How an agent harness works: the agent loop

At the core of every harness is a simple loop:

1. Send the task and the context to the model.
2. The model either answers or asks to use a tool, for example "run this Python code".
3. The harness runs the tool and captures the result.
4. The result goes back to the model.
5. Repeat until the model is done, or until a limit is hit.

The agent loop: the model calls tools until the task is done.

Here's what a minimal harness looks like in Python. It's about 20 lines:

import subprocess

def run_agent(model, task, max_steps=20):
    messages = [
        {"role": "system", "content": "Solve the task. Reply with one bash command, or DONE: <answer>."},
        {"role": "user", "content": task},
    ]
    for _ in range(max_steps):
        reply = model(messages)                      # 1. call the model
        messages.append({"role": "assistant", "content": reply})
        if reply.startswith("DONE:"):                # 2. stop condition
            return reply[5:].strip()
        result = subprocess.run(                     # 3. run the tool
            reply, shell=True, capture_output=True, text=True, timeout=60
        )
        output = (result.stdout + result.stderr)[-5000:]  # 4. truncate
        messages.append({"role": "user", "content": output})  # 5. feed back
    return "Step limit reached."

This isn't a toy. The open-source mini-SWE-agent uses roughly this design, about 100 lines with bash as its only tool, and scores above 74% on the SWE-bench Verified coding benchmark.

What's inside a production harness?

Real harnesses add a lot around the basic loop:

Component	What it does
Agent loop	Calls the model, parses tool calls, repeats until done
Tools	Shell, file editing, code execution, web search, MCP servers
Context management	Summarizes or trims old messages when the context window fills up
Memory	Notes, progress files and skills that survive between sessions
Instructions	System prompt plus project files like AGENTS.md or CLAUDE.md
Permissions & sandbox	Decides what the agent can run without asking; isolates execution
Planning	To-do lists the model updates as it works
Sub-agents	Hands a subtask to a fresh agent and gets back a short summary
Error handling	Retries bad output, detects loops, verifies "I'm done" claims
Tracing	Logs every step so you can debug and improve the agent

Why the harness matters as much as the model

It's tempting to think only the model matters. The benchmarks say otherwise.

LangChain improved its coding agent on Terminal-Bench 2.0 from 52.8% to 66.5%, moving from the top 30 to the top 5, without changing the model. They only changed the harness: they forced a build-and-verify step, gave the agent better context at startup, and added detection for doom loops.

The same pattern shows up on public leaderboards: one model scores differently depending on which harness runs it. This is why "harness engineering" became a discipline of its own in 2026, and why model labs like DeepSeek now release their own harnesses next to their models.

In practice, two products using the same model can feel completely different. The harness is where that difference comes from.

Two meanings of "harness"

You'll see the word used in two ways:

• Runtime (agent) harness: runs the agent. This is what this article is about.
• Evaluation harness: a fixed test rig that runs a model or agent on benchmark tasks and scores it. Examples are lm-evaluation-harness, Inspect AI and Harbor.

The difference is simple: you change a runtime harness to get better results, and you keep an evaluation harness fixed so results stay comparable.

Harness vs. framework vs. model

• Model: the LLM weights. Pure reasoning, no actions.
• Framework / SDK: building blocks for making a harness (LangGraph, Pydantic AI, OpenAI Agents SDK).
• Harness: the assembled, tuned system that actually runs the agent (Codex CLI, OpenCode, Hermes Agent).

The lines blur. LangChain, for example, describes its Deep Agents as an "opinionated harness" built on its LangGraph framework.

Open-source AI agent harnesses (2026)

Below are the most useful open-source harnesses, grouped by what they're for. Licenses and project status change quickly, so check each repository before you build on it.

Coding agent harnesses

Harness	License	Models	Why it's interesting
OpenAI Codex CLI	Apache-2.0	OpenAI-first, configurable	Rust; strong sandboxing; well-documented agent loop
OpenCode	MIT	75+ providers	Terminal, desktop and IDE; very model-agnostic
Aider	Apache-2.0	Any, incl. local	Git-native pair programmer
Cline	Apache-2.0	Any, BYOK	Popular VS Code agent
OpenHands	MIT	Any (LiteLLM)	Docker sandbox; also an SDK
Gemini CLI	Apache-2.0	Gemini	Google's terminal agent
Oh My Pi	MIT	60+ providers	Pi fork with LSP, debugger, sub-agents
DeepSeek Harness (dsh)	MIT	DeepSeek + other providers	Official DeepSeek harness; "everything is a plugin"; developer preview

Note: Claude Code is not open source. Its GitHub repository contains docs and issues, not the source.

General-purpose and personal agent harnesses

Harness	License	Why it's interesting
Hermes Agent (Nous Research)	MIT	Runs on your server, keeps long-term memory, creates its own skills
goose	Apache-2.0	Desktop app, CLI and API; part of the Linux Foundation's Agentic AI Foundation
Deep Agents (LangChain)	MIT	Planning, filesystem and sub-agents built in

Minimal and educational harnesses

Harness	License	Why it's interesting
mini-SWE-agent	MIT	About 100 lines; the best code to read first
smolagents	Apache-2.0	The agent writes Python code as its actions

Agent SDKs (for building your own harness)

SDK	License	Notes
OpenAI Agents SDK	MIT	Native Responses API; other models via LiteLLM
Pydantic AI	MIT	Typed, model-agnostic
Microsoft Agent Framework	MIT	Successor to AutoGen and Semantic Kernel

Harnesses for Jupyter notebooks and data analysis

Project	License	Notes
Jupyter AI	BSD-3	Runs external agents inside JupyterLab
jupyter-mcp-server	BSD-3	Lets any MCP agent edit and run live notebooks

Evaluation harnesses

Harness	License	Notes
Inspect AI	MIT	Agent evals from the UK AI Security Institute
Harbor	Apache-2.0	Official Terminal-Bench harness
lm-evaluation-harness	MIT	Classic benchmark runner for LLMs

Why harnesses matter for data analysis

Coding harnesses mostly run shell commands that forget everything between steps. Data analysis needs something different: a stateful Python kernel, where a DataFrame loaded in step 1 is still in memory in step 10.

That's why a Jupyter notebook is a natural execution environment for a data agent. Every step is a cell, every result is visible, and you can review and rerun what the agent did.

Try MLJAR Studio, a local AI data analyst that turns questions in plain English into Python code, charts, and reproducible notebooks. Use it to explore datasets and run machine learning experiments, with code and results you can inspect, edit, and rerun.

FAQ

What is an AI agent harness in simple terms? It's the software around an LLM that lets it act: it calls the model in a loop, runs tools, manages memory and context, and decides when to stop.

Is an agent harness the same as an agent framework? Not quite. A framework gives you building blocks; a harness is a finished, tuned system built from them.

Is Claude Code open source? No. OpenAI Codex CLI, OpenCode, Aider, Cline and OpenHands are open-source alternatives.

What is the simplest open-source agent harness? mini-SWE-agent. It's about 100 lines of Python with a single bash tool.

Does the harness affect benchmark scores? Yes. LangChain gained almost 14 points on Terminal-Bench 2.0 by changing only its harness.

What is harness engineering? The practice of designing and tuning the harness (tools, context, verification, limits) to get better results from the same model.