# Agentic Harnesses

An **agentic harness** is the runtime environment, control system, and infrastructure that wraps an LLM to turn it into a capable, reliable agent. While the model provides reasoning, the harness provides the *agency* - tools, memory, planning, execution control, safety, observability, and the ability to actually accomplish tasks in the real world.

## What is a Harness?

> *"The model is the brain. The harness is everything else that makes it useful, safe, and reliable."*

A harness is responsible for:
- **Orchestration** - Managing the agent loop (think → act → observe → repeat)
- **Tool execution** - Invoking tools safely with validation and sandboxing
- **State management** - Tracking conversation, tasks, subtasks, and long-term memory
- **Context engineering** - Building optimal context from history, memory, tools, and files
- **Error handling** - Retries, fallbacks, recovery from failures
- **Human-in-the-loop** - Permissions, approvals, and intervention points
- **Observability** - Tracing, logging, cost tracking, and debugging
- **Constraints & safety** - Guardrails, permissions, and resource limits

## Harness vs Framework

| Aspect | Framework | Harness |
|---|---|---|
| **Focus** | Abstractions and patterns for building agents | The runtime system that executes and controls agents |
| **Examples** | LangGraph, OpenAI Agents SDK, PydanticAI | Claude Code, OpenCode, Codex CLI, Cursor Agent, Aider |
| **Scope** | Developer library for composing agents | End-to-end system with UI/CLI, permissions, tools, sandboxing |
| **Ownership** | You build with it | You run it / it runs your agent |
| **Analogy** | Like React (library for building UIs) | Like a browser (runtime environment for web apps) |

## Why Harnesses Matter

The gap between "chat with an LLM" and "agent that ships code" is almost entirely the harness:
- **Reliability**: Handles tool failures, retries, and recovery
- **Safety**: Permission systems prevent destructive actions
- **Context**: Smartly manages large codebases within token limits
- **Workflow**: Implements planning, sub-agents, task tracking
- **Integration**: Deep integration with filesystems, shells, git, browsers
- **Scalability**: Can run long-running tasks, parallelize work

## Vault Structure

```
Harness/
├── README.md                              # This file
├── Fundamentals/
│   ├── Harness-Architecture.md           # Core components and design patterns
│   ├── Agent-Loop.md                     # The think-act-observe cycle
│   ├── Harness-vs-Framework.md           # Distinctions and when to use each
│   └── Design-Principles.md              # Principles for building robust harnesses
├── Core-Components/
│   ├── System-Prompt.md                  # Instructions, rules, and agent identity
│   ├── Tool-Registry.md                  # Tool definition, discovery, and execution
│   ├── Context-Builder.md                # Assembling optimal context
│   ├── Memory-System.md                  # Short-term, long-term, and project memory
│   ├── Task-Management.md                # Planning, todos, subtasks
│   └── Permission-System.md              # Approvals, allowlists, sandboxes
├── Execution/
│   ├── Execution-Engine.md               # Orchestration and control flow
│   ├── Sub-Agents.md                     # Spawning and coordinating sub-agents
│   ├── Parallel-Execution.md             # Concurrent tool calls and tasks
│   ├── Error-Recovery.md                 # Retries, fallbacks, self-correction
│   └── Streaming.md                      # Real-time output and thinking
├── Integration/
│   ├── CLI-vs-Desktop-vs-Web.md          # Deployment models
│   ├── Filesystem-Integration.md         # Reading, writing, editing files
│   ├── Shell-Integration.md              # Command execution and safety
│   ├── Git-Integration.md                # Version control workflows
│   └── MCP-Integration.md                # Connecting external tools
├── Production/
│   ├── Observability.md                  # Tracing, logging, telemetry
│   ├── Cost-Tracking.md                  # Token usage, budgets, optimization
│   ├── Security.md                       # Sandboxing, secrets, permissions
│   ├── Reliability.md                    # Timeouts, cancellation, recovery
│   └── Evaluation.md                     # Testing harness effectiveness
└── Building-A-Harness/
    ├── Minimal-Harness.md                # Build a simple harness from scratch
    ├── Implementation-Guide.md           # Step-by-step implementation
    ├── Testing-Strategy.md               # Testing your harness
    └── Reference-Implementations.md     # Study real harnesses
```

## Quick Navigation

| If you're... | Start Here |
|---|---|
| **New to harnesses** | `Fundamentals/Harness-Architecture.md` → `Fundamentals/Agent-Loop.md` |
| **Understanding the difference** | `Fundamentals/Harness-vs-Framework.md` |
| **Building a harness** | `Building-A-Harness/Minimal-Harness.md` → `Building-A-Harness/Implementation-Guide.md` |
| **Designing tools/permissions** | `Core-Components/Tool-Registry.md` → `Core-Components/Permission-System.md` |
| **Adding sub-agents** | `Execution/Sub-Agents.md` → `Execution/Parallel-Execution.md` |
| **Making it production-ready** | `Production/Observability.md` → `Production/Security.md` |
| **Studying existing ones** | `Building-A-Harness/Reference-Implementations.md` |

## Core Principles

1. **Model-agnostic when possible** - Support multiple providers/models
2. **Deterministic control flow** - The harness controls the loop, not the model
3. **Safety by default** - Permissions and validation before execution
4. **Observable** - Everything should be traceable and debuggable
5. **Composable** - Tools, sub-agents, and capabilities are modular
6. **Context-aware** - Smart context building beats dumping everything
7. **Resilient** - Graceful handling of failures and rate limits
8. **User-centric** - Clear feedback, easy intervention

## Related Notes

- [[../Foundations/Agent-Definitions.md]] — What makes something an agent
- [[../Architectures/Single-Agent-Patterns.md]] — Agent patterns the harness implements
- [[../ToolUse/Function-Calling.md]] — Tool calling mechanics
- [[../ToolUse/MCP-Protocol.md]] — Tool interoperability
- [[../StateManagement/Checkpointing.md]] — State persistence
- [[../Production/Deployment-Architecture.md]] — Deploying agent systems
- [[../../Systems Engineering/Verification-Validation/V-Model-And-VV-Planning.md]] — Testing harnesses

## Sources

* Anthropic - Building Effective Agents, Computer Use, Tool Use  
* OpenAI - Agents SDK documentation  
* LangGraph documentation  
* Claude Code, Codex CLI, OpenCode source patterns  
* Cognition (Devin), Amp, Cursor engineering blogs  
* "The Rise of the Agentic Harness" - industry discussions  
* SWE-bench and agent evaluation research