AI harness vs agent framework

AI harness vs agent framework is a choice between two layers of the stack: a harness wraps agent tools that already exist, such as Claude Code or Codex CLI, with project structure, while an agent framework is a software library for building your own agent on top of a model API. If your goal is to get coding work done on your own repositories, a harness (or a disciplined manual workflow) is usually the right layer, because the agent loop, file editing and command execution are already built and maintained by the vendor. If your goal is to put an agent inside your own product, run a custom loop over your own tools, or control every prompt and tool call, a framework is the right layer, because a harness gives you very little control over the agent's internals. The two are not rivals. Many teams use a framework to build something customer-facing and a harness or plain CLI sessions for their own development. This page compares what each gives you, what each costs, and who each fits.

What an agent framework gives you

An agent framework is a library. It gives you building blocks: a loop that sends messages to a model, parses tool calls, runs your functions and feeds the results back; ways to define tools with schemas; state and memory helpers; sometimes multi-agent patterns, tracing and evaluation hooks. Model providers publish their own agent SDKs, and there are several open-source frameworks.

What you get is control. You decide the system prompt, which tools exist, what each tool may do, how errors are handled, when the loop stops and what gets logged. You can build an agent that only answers questions about your billing data, or one that triages support tickets with three narrow tools.

What you take on is everything else. You own the tool implementations, including any that write files or run shell commands, and therefore their safety. You own evaluation: whether the agent is actually good at the job. You own upgrades when the model or framework changes. For coding work specifically, rebuilding what a mature coding CLI already does (repository exploration, careful editing, test running, permission prompts) is a large project in itself, and the result is usually less capable for a long time.

What a harness gives you

A harness takes the opposite approach. It treats existing agent CLIs as the workers and adds the project structure around them: which task the agent is working on, what context it gets, what it may touch, how the result is checked and where the record goes. The agent's internal loop stays the vendor's. When Claude Code or Codex CLI improves, the harness benefits without code changes on your side.

The cost is less control over the agent itself. A harness can choose what to put in front of the agent, launch it in a particular mode (for example a read-only review session) and check what came back, but it cannot rewrite how the agent reasons or which internal tools it calls. Protections a harness adds around a CLI are tripwires and checks, not a rewrite of the agent's permissions, and they should be honest about their gaps. A harness also depends on the CLI's behavior staying compatible across versions.

The general idea is explained in what a project management harness is, and the split between the worker and the layer around it is covered in coding agent vs project manager.

Side by side: control, effort and risk

Control. A framework controls the agent's loop, tools and prompts. A harness controls the task, context, scope and acceptance around a loop it does not own.

Effort to start. With a harness you configure projects and tasks and use the CLI you already have. With a framework you write and host code before the first useful run.

Where safety lives. In a framework, safety is whatever your tools allow: a tool that cannot delete files cannot be talked into deleting files. Around a CLI, safety comes from the CLI's own permission and sandbox settings plus whatever checks the harness adds; see scope control for AI agents for how those layers combine.

Evaluation. Both need it, and neither gives it for free. Whatever you choose, test it on tasks with independent correctness checks, as described in how to evaluate an AI coding workflow tool.

Lock-in. A framework ties you to its abstractions and, often loosely, to a model provider. A harness ties you to the CLIs it supports and to its own project format, so check that your project data stays readable without it.

Who each fits

Choose a framework if you are building an agent as a product or a product feature, if the agent needs tools that no coding CLI offers (your internal APIs, a domain database), if you need full control of prompts and logs for compliance reasons, or if the task is not software development at all.

Choose a harness, or a manual equivalent, if you are a developer or team using agents to build and maintain your own software, if the agent CLIs already do the coding well and your problem is everything around them, or if you want several agents working on one project without writing an orchestration layer. Coordinating several agents on one project is a typical reason.

Use neither if a single agent session on a small repository already does what you need. Plain sessions plus a notes file are a legitimate setup, and adding layers you do not need costs attention.

Combining them is normal. A team might build a customer-facing support agent with a framework and develop that very codebase with Claude Code inside a harness. The question to ask is not which is better but which layer your current problem lives in: inside the agent's loop, or around it.

QUESTIONS

Should I build my own coding agent with an agent SDK?

Usually not if the goal is coding on your own repositories. Mature coding CLIs already handle exploration, editing, test runs and permission prompts, and rebuilding that well takes a long time. Build your own when you need tools those CLIs lack, full control of prompts and logs, or an agent embedded in a product you ship.

What is the difference between an agent framework and an agent CLI?

A framework is a library you program against: you configure the loop, write the tools and prompts, and host the result. An agent CLI is a finished program, such as Claude Code or Codex CLI, that you run in a terminal against your repository. A framework is for building agents; a CLI is an agent you use.

Can a harness add safety controls to an existing coding agent?

Partly. A harness can choose which mode the agent starts in, check commands and touched files against declared boundaries, and refuse to accept results that fail checks. It cannot change the agent's internals, and pattern-based checks miss things. Treat harness controls as an extra layer on top of the CLI's own permission and sandbox settings, not a replacement.

RELATED GUIDES

• What is a project management harness?

RELATED HARNESS PAGES

• AI coding agent vs AI project manager AI coding agent vs AI project manager: an agent does one task, a project layer holds plan, context, checks and record across many. Neither replaces the other.
• How to evaluate an AI coding workflow tool How to evaluate an AI coding workflow tool without trusting demos: matched pairs, independent checks, every failure kept, and limits stated plainly.
• Keeping AI coding agents within scope Keeping AI coding agents within scope: declare paths, approve them separately with an expiry, check writes during the run and compare the diff after.
• multi-agent project coordination Multi-agent project coordination: keep Claude and Codex work on one project organized with shared cards, scope, authority and review.