Skip to main content
What Is an Agent Harness? The Part Around the Model

What Is an Agent Harness? The Part Around the Model

KU
· Founder & Chief Editor
• 7 min read•

The model picks the next action. The harness decides what it sees, what it may touch, and when it stops. In production, the harness is where most agent failures live.

Key takeaways

  • An agent harness is the software around a language model that turns it into an agent.
  • It runs the loop, executes tools, manages the context window, enforces permissions and fires hooks.
  • The same model behaves very differently in different harnesses, so treat the harness as infrastructure you configure, version and audit.

An agent harness is everything around the model: the loop that calls it, the tools it can run, the context it sees, the permissions that stop it and the hooks that watch it. The model chooses the next step. The harness decides whether that step happens. When a production agent misbehaves, the cause is usually in the harness.

Verified against

Claude Agent SDK overview, Claude Code hooks, permissions and headless docs (Claude Code 2.1), Anthropic's engineering post on long-running agent harnesses, and the Terminal-Bench 4.1 leaderboard. Checked November 2026.

Same model, different harness, different agent

A model API returns text, including requests to call a tool. It runs nothing. The harness parses the tool call, executes it, feeds the result back and decides when to stop.

Anthropic describes its Claude Agent SDK as "a general-purpose agent harness", and its docs say the SDK gives you "the same tools, agent loop, and context management that power Claude Code." In Anthropic's own long-running-agent experiments, the fix for agents that declared victory early was not a new model. It was harness work: an initializer prompt for the first context window, a feature list in a JSON file, progress notes, and git commits as checkpoints.

Benchmarks make the point too. The Terminal-Bench 4.1 leaderboard lists every score as a model plus an agent, because the pair is what got measured.

The seven parts every harness has

Anatomy of an agent harness: the model in the centre, surrounded by the agent loop, tool registry, context manager, permission layer, sandbox, hooks and session state; a tool call passes permissions, a PreToolUse hook and the sandbox before it reaches the environment

  1. The loop. Call the model, run the requested tools, append results, repeat until the model stops or a turn limit hits. The whole loop fits in 50 lines, as our guide to building AI agents shows.
  2. The tool registry. Built-in tools (read, edit, shell, fetch) plus anything exposed over MCP.
  3. The context manager. Decides what stays in the window: system prompt, project memory files, truncated tool output, and compaction when the window fills.
  4. The permission layer. Allow, ask and deny rules evaluated before every tool call.
  5. The sandbox. The filesystem and network boundary the tools actually run inside. Permissions say what the agent may ask for; the sandbox limits what a mistake can reach.
  6. Hooks. Your code, run on lifecycle events. Claude Code currently documents 33 of them, from SessionStart to PreToolUse, PreCompact and Stop.
  7. Session state. Transcripts, resumable sessions, subagents with their own clean context, and files the agent writes for its future self.

Context is the part that fails first

Long tasks break on context before reasoning. A 40,000-line test log or a dozen large diffs push the original instructions out of the window or into a summary. Compaction keeps the session alive but loses detail; Anthropic's harness post says plainly that "compaction isn't sufficient" for multi-hour work.

The same context window at four moments: at the start it holds the system prompt and the task constraints; mid-task a raw test log fills most of it; after compaction a summary replaces early turns and drops a constraint; with harness fixes, a progress file is re-read and tool output is truncated so the constraint survives

What works is structural. Truncate tool output at the harness, not in the prompt. Push large searches into a subagent so only its conclusion returns. Keep durable state in files (a task list, a progress log) that the agent re-reads after compaction instead of trusting its summary.

Permissions and hooks are your policy layer

One tool call step by step: the model proposes a call, permission rules are checked deny then ask then allow, a PreToolUse hook runs and can block with exit code 2, then the tool runs in the sandbox and its truncated output goes back into context for the next turn

In Claude Code, deny rules win over ask rules, which win over allow rules, and lists merge across user, project and managed settings files. A project-level .claude/settings.json can therefore ship a baseline every developer and CI job inherits:

.claude/settings.json
{
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)", "Bash(git push *)"]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "if": "Bash(rm *)", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh" }
        ]
      }
    ]
  }
}

A PreToolUse hook that exits with code 2 blocks the call, and the model sees the hook's stderr as the denial reason. That makes hooks the right place for rules a pattern cannot express, such as "no terraform apply outside a plan file" or "no writes under infra/prod/". For unattended runs, pin the rest on the command line:

Bash
claude -p "Fix the failing unit tests in src/billing" \
    --allowedTools "Read,Edit,Bash(npm run test *)" \
    --max-turns 20 --output-format json

--max-turns has no default limit, so set one. The same principles apply to any harness; our post on agent tool boundaries and confirmations covers the read/write split in detail.

Build, buy, or configure

OptionYou getYou ownFits when
Claude Code CLI (claude -p)Full harness, settings files, hooksConfig and CI wiringCoding and ops tasks in a repo
Claude Agent SDKThe same harness as a Python or TS libraryYour app around itEmbedding an agent in a product
Graph frameworks (LangGraph and similar)State machine, checkpointsTools, permissions, sandboxFixed multi-step workflows
Your own loopExactly what you writeEverythingOne narrow task, few tools

Your own loop is fine until you need compaction, permission rules and an audit trail, the parts that take months to get right. For running these CLIs inside pipelines, see AI CLI agents in CI.

Questions people ask

Is an agent harness the same as an agent framework?

Overlapping, not identical. A framework gives you building blocks (graphs, memory classes, tool wrappers) and you assemble the runtime. A harness is the assembled runtime: a working loop with context management, permissions and hooks already wired.

Does the harness matter more than the model?

For a fixed task, a weak harness caps what any model can do: it can drown the model in output, lose instructions to compaction or let it run without a stop condition. Benchmarks report the model and agent together for this reason.

The decision, concretely

  • Agent works in a git repo on code or config? Use an existing harness and commit its settings file with the repo.
  • Agent ships inside your product? Use an SDK harness rather than writing compaction and permissions yourself.
  • Running unattended in CI? Allowlist tools explicitly, set --max-turns, and run in a container you can throw away.
  • A safety rule you cannot express as a pattern? Write a PreToolUse hook and test it like any other code.

The call we'd make

Treat the harness as infrastructure. Check its settings file into the repo, review permission changes like IAM changes, put hard rules in hooks rather than prompts, and log every tool call. Pick the model second. The caveat: a harness cannot rescue a task the model fundamentally cannot do, so run a small eval before you blame the configuration.

Sources

Explore topics:LLMAIDevOps
React
Share this post
Cite this article
Plain text

Kiril Urbonas (2026). What Is an Agent Harness? The Part Around the Model. DevOpsNess. https://www.devopsness.com/blog/what-is-an-agent-harness

Markdown

[What Is an Agent Harness? The Part Around the Model](https://www.devopsness.com/blog/what-is-an-agent-harness) (Kiril Urbonas, DevOpsNess, 2026-11-20)

KU

Kiril Urbonas

Founder & Chief Editor

608 articles
View all articles by Kiril Urbonas

You might have missed

Evergreen posts worth revisiting.