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
- Model-agnostic when possible - Support multiple providers/models
- Deterministic control flow - The harness controls the loop, not the model
- Safety by default - Permissions and validation before execution
- Observable - Everything should be traceable and debuggable
- Composable - Tools, sub-agents, and capabilities are modular
- Context-aware - Smart context building beats dumping everything
- Resilient - Graceful handling of failures and rate limits
- User-centric - Clear feedback, easy intervention
Related Notes
- Agent Definitions — What makes something an agent
- Single Agent Patterns — Agent patterns the harness implements
- Function Calling — Tool calling mechanics
- MCP Protocol — Tool interoperability
- Checkpointing — State persistence
- Deployment Architecture — Deploying agent systems
- V Model And VV Planning — 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