What is an agent harness? Examples, flowcharts, and popular harnesses in 2026

In 2023 everyone talked about prompt engineering. In 2025–26, teams shipping real agents talk about harness engineering.

Short formula:

Agent = Model + Harness

The model emits tokens. The harness connects the model to the world: the loop, tools, permissions, sandbox, context packing, verification, and human-in-the-loop (HITL).

For: apply-AI / fullstack builders — chatboxes, coding agents, internal agents — not people training base models.

Takeaway: Swapping models rarely fixes a broken agent. Fixing the harness (tools + verify + permissions) does.

Related: MCP · Skill · Subagent · Learn → AI Roadmap (Agents + harness phase).

---

1 · A harness is not “an agent framework”

People confuse harnesses with LangChain / LangGraph. In practice (including 2026 source audits of ~11 production coding harnesses), most runtimes ship a hand-rolled async loop. Few import a generic agent framework.

Thoughtworks / Martin Fowler’s framing: your configuration layer around a coding agent is an outer harness — guides (steer before) + sensors (correct after).

---

2 · Flowchart 1 — one agent step

This is the spine of most coding agents (Claude Code, Cursor, Codex, OpenHands…):

                    ┌─────────────┐
                    │  User goal  │
                    └──────┬──────┘
                           ▼
              ┌────────────────────────┐
              │  Context pack          │
              │  system + rules +      │
              │  skills + file/RAG     │
              └────────────┬───────────┘
                           ▼
                 ┌──────────────────┐
            ┌───►│  LLM decide      │◄──────────────────────────┐
            │    │  (think / act)   │                           │
            │    └────────┬─────────┘                           │
            │             │                                     │
            │      ┌──────┴──────┐                              │
            │      ▼             ▼                              │
            │   Text reply    Tool call                         │
            │      │             │                              │
            │      │             ▼                              │
            │      │      ┌──────────────┐                      │
            │      │      │  Permission  │──deny──► explain     │
            │      │      │  allowlist   │                      │
            │      │      └──────┬───────┘                      │
            │      │             ▼                              │
            │      │      ┌──────────────┐                      │
            │      │      │  Sandbox /   │                      │
            │      │      │  workspace   │                      │
            │      │      └──────┬───────┘                      │
            │      │             ▼                              │
            │      │      ┌──────────────┐                      │
            │      │      │  Execute     │                      │
            │      │      │  (fs/shell)  │                      │
            │      │      └──────┬───────┘                      │
            │      │             ▼                              │
            │      │      ┌──────────────┐     fail             │
            │      │      │  Verify      │─────────────┐        │
            │      │      │  lint/test   │             │        │
            │      │      └──────┬───────┘             │        │
            │      │          ok │                     ▼        │
            │      │             │              tool result     │
            │      ▼             └───────────────────► append ──┘
            │   Done / HITL ask human
            └──

How to read it: “Done” is not the model announcing success — verify (tests/lint/scripts) or HITL is the gate.

---

3 · Seven harness blocks (minimal → serious)

From production coding-harness anatomy:

Apply-AI / SME: ship 1–6. Add 7 when you have a team or you’re selling an agent platform.

---

4 · Example 1 — support chatbox (not a coding agent)

Goal: FAQ widget for a shop; escalate when unsure.

User message
    │
    ▼
[Input guard] ── PII / injection? ──► refuse / sanitize
    │
    ▼
[Retrieve] FAQ chunks (RAG) + order policy
    │
    ▼
[LLM] draft answer + confidence
    │
    ├── low confidence ──► [HITL / human queue]
    │
    ▼
[Output guard] no invented prices / legal claims
    │
    ▼
Reply + trace log (Langfuse-style)

The harness here: guards + RAG + HITL + traces — not “clever prompts.” Models are swappable; those blocks are what you sell.

---

5 · Example 2 — mini coding agent (Roadmap harness project)

Goal: “Fix bug X in the repo; only mark Done when tests pass.”

Goal: fix failing test auth.spec.ts
    │
    ▼
[Skill: ship-check] load playbook
    │
    ▼
Agent: read failing test + source
    │
    ▼
Agent: edit files (allowlist src/** only)
    │
    ▼
Harness hook: pnpm test auth.spec.ts
    │
    ├── fail ──► append output ──► agent retry (max 3)
    │
    ▼
pass → summarize diff → human merge

No test hook → agents hallucinate Done. That’s why Flo-style platform diagrams always draw Agent Sandboxes + Evaluation.

---

6 · Guides vs sensors (outer harness)

Thoughtworks framing:

Rule of thumb: computational sensors on every agent edit (cheap). Inferential sensors on PR / nightly (expensive).

Human steering loop:

1. Agent repeats a mistake →
2. Add a short guide or a sensor that catches it →
3. Next time, less manual review.

---

7 · Popular harnesses in 2026

Product-feel table — not a lab leaderboard:

Cross-cutting note from community source audits: skills and MCP are widespread; coding harnesses often use deterministic retrieval (grep/paths), not “vector everything.”

---

8 · Flowchart 2 — which harness? (apply AI)

What do you need?
    │
    ├── Daily code edits in a repo
    │       └── Cursor or Claude Code / Codex
    │             + outer harness (rules + tests)
    │
    ├── Customer-facing agent (chatbox / RAG / tools)
    │       └── Build a thin harness:
    │             tool allowlist + HITL + 30 eval cases
    │
    ├── Corp “ChatGPT for company data”
    │       └── Platform (Open WebUI / Dify / custom)
    │             + audit + quota + tool registry
    │
    └── Research / agent benchmarks
            └── OpenHands / SWE-agent stack

Don’t clone a full Flo diagram (multi-frontier + RL) as a one-person team. Clone the pattern: sandbox + tools + eval.

---

9 · Minimal harness checklist (ship this week)

Paste into Notion / HARNESS.md:

1. Clear goal — one Done sentence (e.g. “test X green”).
2. Tool allowlist — read; write src/**; shell only pnpm test / lint.
3. Sandbox — no .env, no rm -rf /.
4. Verify hook — failing tests ≠ Done.
5. HITL — merge, deploy, email customer = ask a human.
6. Trace — log tool calls + tokens (even a JSON file).
7. Small eval — 10–30 golden cases; re-run when prompts/skills change.
8. 1–3 Skills — repeat playbooks (review, ship-check, incident).

That’s the spirit of Phases 4–5 on this site’s AI Roadmap.

---

10 · Anti-patterns

1. Buy a stronger model when the real bug is a missing test hook.
2. Fill settings with MCP but no skills/playbooks → many hands, no procedure.
3. Trust “Done” without verification.
4. Sandbox = raw laptop with admin rights.
5. Eval by vibes (“answers felt fine today”) — no golden set.
6. 50-page outer harness — agents don’t read novels; keep guides short and sensors executable.

---

Closing

Harness isn’t a buzzword replacing prompts. It’s product discipline: models aren’t trustworthy alone; you wrap them with permissions, environment, and quality gates.

Three lines to keep:

1. Agent = Model + Harness.
2. Done = verify (or HITL), not model prose.
3. Outer harness (rules/skills/tests) is what apply-AI can still control while models churn monthly.

---

Next step: open the Roadmap “Agents + harness” phase and ship a mini coding agent with a test hook. One demo repo beats one architecture slide.