<!-- Social preview metadata. Set the repo's social preview image in GitHub Settings → Social preview. The Open Graph / Twitter tags below are picked up by some third-party renderers that parse the raw README. --> <meta property="og:title" content="Agentic Harness — The Open Agent Harness" /> <meta property="og:description" content="Write the manual. Agentic Harness compiles it into a team of specialists that follows it to the letter." /> <meta property="og:url" content="https://github.com/frangelbarrera/agentic-harness" /> <meta property="og:type" content="website" /> <meta name="twitter:card" content="summary_large_image" /> <meta name="twitter:title" content="Agentic Harness — The Open Agent Harness" /> <meta name="twitter:description" content="Write the manual. Agentic Harness compiles it into a team of specialists that follows it to the letter." /> <div align="center"> <img src="docs/logo-agentic-harness.png" alt="Agentic Harness logo" width="200" />

Agentic Harness

The Open Agent Harness

Write the manual. Agentic Harness compiles it into a team of specialists that follows it to the letter.

Manifesto · Documentation · Examples · Contributing

</div> <p align="center"> <img src="docs/agentic-harness-demo.gif" alt="Agentic Harness demo" width="700" /> </p>

---

If your framework needs a debugger for your debugger, it is the wrong framework.

Quick install

pip install arnes

Why Agentic Harness?

Most agent frameworks are black boxes: you can't see the prompts, can't control the costs, and can't audit what happened. Agentic Harness fixes this with three principles:

1. Transparency — Every prompt, decision, and cost is logged to a markdown audit log you can git diff.
2. Cost control — Hierarchical budget enforcement with circuit breaker. An agent can't burn your API budget silently.
3. Vendor neutrality — Default model is local (Ollama, $0). Switching providers is one line. No vendor lock-in.

Who is Agentic Harness for?

• Backend engineers who need production agents with budgets, audit trails, and compliance
• ML engineers who need reproducible benchmarks across providers
• Researchers who need citation-ready, replayable experiments
• DevOps teams who need MCP server integration with auth and rate limiting

Not for you if you want a visual builder, hosted SaaS, or multi-agent crews (v0.4+).

---

What it looks like

    ___
   /   |  _________ ___   _______
  / /| | / ___/ __ `__ \ / ___/ /
 / ___ |/ /  / / / / / // /__/ /
/_/  |_/_/  /_/ /_/ /_/ \____/_/
        The Open Agent Harness

A manual in YAML:

# manuals/audit-pr.yaml
name: audit-pr
objective: Audit a Pull Request in a structured way
budget_usd: 0.50

steps:
  - id: read_diff
    specialist: "@reviewer"
    input:
      pr_number: 1234
      repo: "my-org/my-repo"
      focus: "Read the diff and structure it for analysis"

  - id: security_audit
    specialist: "@reviewer"
    input: "{{ steps.read_diff.output }}"
    focus: "Security review: auth flows, SQL injection, XSS, path traversal"
    if_not_met:
      action: call
      specialist: "@reviewer"
      input:
        focus: "Comment that the PR is blocked by security review"

  - id: parallel
    parallel:
      - id: lint
        specialist: "@reviewer"
        input:
          code: "{{ steps.read_diff.output }}"
          focus: "Code quality: idioms, naming, complexity"
      - id: tests
        specialist: "@tester"
        input:
          code: "{{ steps.read_diff.output }}"
          focus: "Verify tests cover the PR changes"

  - id: synthesis
    specialist: "@reviewer"
    input:
      diff: "{{ steps.read_diff.output }}"
      security: "{{ steps.security_audit.output }}"
      lint: "{{ steps.parallel.lint.output }}"
      tests: "{{ steps.parallel.tests.output }}"
      focus: "Synthesize into a final verdict: approve / request_changes / reject"

You run it (mock LLM, no network, $0 cost):

$ arnes run manuals/hello-world.yaml --mock

Agentic Harness compiles the manual into a DAG, wakes the specialists in sequence, applies token optimization and verification layer on every LLM call, and returns:

╭────────────────────────────────────────────────────────────────────╮
│ Agentic Harness — Executing playbook                                         │
│   Name: hello-world                                                │
│   Objective: Demonstrate the basic Agentic Harness flow with a simple manual │
│   Model: ollama/llama3.2                                           │
│   Budget: $0.50                                                    │
╰────────────────────────────────────────────────────────────────────╯
2026-07-30 16:42:44 [info] llm_call_tracked  budget=0.5 cost_usd=0.0 \
      model=ollama/llama3.2 tokens_in=335 tokens_out=15 total_spent=0.0
2026-07-30 16:42:44 [info] llm_call_tracked  budget=0.5 cost_usd=0.0 \
      model=ollama/llama3.2 tokens_in=370 tokens_out=38 total_spent=0.0

✅ Manual executed

Steps executed: 2
Steps failed: 0
Duration: 0.01s
Tokens in/out: 705/53
Total cost: $0.0000

Run log saved to: arnes-run-hello-world-20260730-164244.md

The run log is a markdown file with every step, every decision, every prompt sent, every response received. You can diff it, version it, share it:

# Audit log Agentic Harness — Thread 0b6ac82e-2600-42f5-a6ca-62e016df7961

**Total events:** 7

## [2026-07-30T16:42:44] step_started
**Step:** `plan`  ·  **Specialist:** `@planner`

## [2026-07-30T16:42:44] assistant_message
**Step:** `plan`  ·  **Specialist:** `@planner`
```json
{
  "model": "ollama/llama3.2",
  "tokens_in": 335,
  "tokens_out": 15,
  "cost_usd": 0.0,
  "cached": false
}
```

## [2026-07-30T16:42:44] step_completed
...

Want to see the whole flow end-to-end? Run the narrated demo script:

./scripts/demo.sh            # print to terminal
./scripts/demo.sh --record demo.tape && vhs demo.tape   # render a GIF

---

Features

| Category | Feature | Status | |---|---|---| | Agent loop | Stateless reducer (state, event) → state | ✅ v0.1 | | | ReAct tool-use loop in specialists | ✅ v0.1 | | | AG-UI streaming compatible | 🚧 v0.2 | | Specialists | 12 pre-built (planner, coder, reviewer, tester, debugger, researcher, security-auditor, devops-engineer, data-scientist, product-manager, market-analyst, cost-estimator) | ✅ v0.1 | | | Playbook Library with 13 domain templates + TaskRouter | ✅ v0.1 | | Playbook DSL | Declarative YAML compiled to DAG | ✅ v0.1 | | | Conditional branches (if_not_met) | ✅ v0.1 | | | Parallel branches (true asyncio.gather) | ✅ v0.1 | | | Retry with backoff | 🚧 v0.2 (schema defined, execution pending) | | | HITL gates (pause and request approval) | ⚠️ v0.1 (auto-reject in non-interactive) | | | Actor-critic review loop (--loops, step.review) | ✅ v0.1 | | MCP | Agentic Harness as MCP server (Claude Desktop, Cursor, Cline, Zed) | ✅ v0.1 | | | Agentic Harness as MCP client (consume external MCP servers) | 🚧 v0.2 | | | HTTP/SSE transport | 🚧 v0.2 (stdio only in v0.1) | | Token Optimization | Automatic model routing by complexity | ✅ v0.1 | | | Semantic cache | ✅ v0.1 | | | Context compaction | 🚧 v0.2 | | | Few-shot pruning | 🚧 v0.3 | | Verification Layer | Structured outputs with pydantic | ✅ v0.1 | | | Refusal pattern (no hallucination, says "I don't know") | ✅ v0.1 | | | Confidence gate | 🚧 v0.2 | | | Critic loop (actor-critic iterative refinement) | ✅ v0.1 | | | Grounding RAG optional | 🚧 v0.4 | | Cost Guard | Hierarchical budget (org → project → agent → task) | ✅ v0.1 | | | Temporal circuit breaker (max USD/min) | ✅ v0.1 | | | Automatic model fallback | ✅ v0.1 | | | Cost HITL (pause at X% exceeded) | ⚠️ v0.1 (log warning, auto-pause pending) | | Sandbox | Docker hardened (Tier 1 dev-local) | ✅ v0.1 (auto-detected when docker is on PATH; falls back to gated local exec via ARNES_DEV_MODE=1) | | | gVisor (Tier 2 production) | 🚧 v0.4 | | Multi-agent | Single-agent default | ✅ v0.1 | | | Crew (sequential/hierarchical) | 🚧 v0.4 | | | A2A with trust | 🚧 v0.5 | | Observability | Structured event log | ✅ v0.1 | | | Auditable markdown audit log | ✅ v0.1 | | | OpenTelemetry exporter | 🚧 v0.3 | | Benchmarks | BenchmarkRunner with multi-seed + concurrent + p95 | ✅ v0.1 |

---

Agentic Harness vs the rest

| Dimension | LangChain | CrewAI | OpenAI Agents SDK | Agentic Harness | |---|---|---|---|---| | How you define agents | Python procedural | Agent/Crew/Task classes | @agent decorator | Declarative YAML | | Distribution | pip library | pip library | pip library (OpenAI-only) | MCP server + library | | Pre-built specialists | ❌ | ❌ | ❌ | ✅ 12 ready | | Curated playbooks | ❌ | ❌ | ❌ | ✅ 10 manuals + 13 domain templates | | Token optimization | Manual | ❌ | ❌ | ✅ Automatic middleware | | Anti-hallucination | DIY | ❌ | ❌ | ✅ 3 layers (structured + refusal + actor-critic) | | Budget enforcement | max_tokens basic | max_tokens basic | ❌ | ✅ Hierarchical + circuit breaker | | Vendor-neutral | Partial | ✅ | ❌ | ✅ 100% (default Ollama local) | | Prompts visible | ❌ | ❌ | ❌ | ✅ Files on disk |

---

Alignment with the 12-factor-agents manifesto

Agentic Harness aligns explicitly with the 12 factors:

| Factor | Description | Agentic Harness | |---|---|---| | 1 | Natural language > structured language | ✅ Declarative YAML | | 2 | Tools are structured outputs | ✅ Pydantic schemas | | 3 | Give agents composable, discrete tools | ✅ Specialist registry | | 4 | Agents are switching loops, not while loops | ✅ Event-driven reducer | | 5 | Simple but powerful primitives | ✅ Thread + Specialist + Tool | | 6 | Use the right tool for the job | ✅ Model routing | | 7 | Humans are tools, not gates | ✅ HITL as a typed tool call | | 8 | Make agents easy to debug | ✅ Markdown audit log | | 9 | Make agents observable | ✅ Event log + OTel (v0.3) | | 10 | Replayable from any point | ✅ Stateless reducer + checkpoint | | 11 | Be a state machine, not a DAG | ⚠️ We are a DAG by design (declarative) | | 12 | Deploy as a server, not a library | ✅ Native MCP server |

---

Installation

pip install arnes

Or install from source for development:

git clone https://github.com/frangelbarrera/agentic-harness.git
cd agentic-harness
pip install -e ".[dev]"

Quickstart (60 seconds)

# 1. Install (see Installation above)

# 2. Create your first manual
arnes init --manual hello-world

# 3. Run it with the mock LLM (no network, $0 cost)
arnes run manuals/hello-world.yaml --mock

# 4. Stream a specialist's response token-by-token
arnes stream @planner --task "Plan a blog post about Agentic Harness" --mock

# 5. Run it with Ollama local (free, requires `ollama pull llama3.2`)
arnes run manuals/hello-world.yaml

# 6. Stream playbook step events as they complete
arnes run manuals/hello-world.yaml --mock --stream

# 7. Benchmark every playbook (multi-seed, p95, concurrent)
arnes benchmark --seeds 5 --concurrent 4

If you do not have Ollama installed, Agentic Harness detects it and guides you. To use Anthropic/OpenAI, set the env var and Agentic Harness does the rest:

export ANTHROPIC_API_KEY=sk-ant-...
ar