# Harness Architecture

A well-designed agentic harness has a layered architecture. Understanding these layers is key to building or extending one.

## High-Level Architecture

```mermaid
graph TD
    A[User Interface - CLI/Desktop/Web] --> B[Session Manager]
    B --> C[Agent Loop Orchestrator]
    C --> D[Context Builder]
    C --> E[Model Client]
    C --> F[Tool Registry & Executor]
    C --> G[Task Manager]
    F --> H[Sandbox/Environment]
    F --> I[Filesystem/Shell/Git]
    G --> J[Sub-Agent Spawner]
    J --> C
    D --> K[Memory System]
    D --> L[Project Context]
    B --> M[State Store/Checkpointer]
    C --> N[Permission System]
    C --> O[Observability/Tracing]
    
    style A fill:#e1f5fe
    style C fill:#fff3e0
    style F fill:#f3e5f5
    style H fill:#ffcdd2
    style O fill:#e8f5e9
```

## Core Layers

### 1. Interface Layer
The user-facing layer for interacting with the agent.

| Component | Purpose | Examples |
|---|---|---|
| **CLI** | Terminal-based interaction | Claude Code, OpenCode, Codex CLI, Aider |
| **TUI** | Rich terminal UI with panels, diffs | OpenCode TUI, Continue CLI |
| **Desktop App** | Native GUI application | Cursor, Continue Desktop, Copilot |
| **Web UI** | Browser-based interface | LangGraph Studio, OpenWebUI |
| **API** | Programmatic access | Agent SDKs, custom integrations |

### 2. Session & State Layer
Manages conversation state, history, and persistence.

| Component | Purpose |
|---|---|
| **Session Manager** | Tracks active sessions, threads, and users |
| **Checkpointer** | Persists state for resumption and time-travel |
| **History Store** | Stores conversation history, tool calls, results |
| **Configuration** | User preferences, project settings, rules |

### 3. Orchestration Layer (The Heart)
Controls the agent's behavior and decision-making flow.

| Component | Purpose |
|---|---|
| **Agent Loop** | The core think-act-observe cycle |
| **Planner** | Task decomposition and planning |
| **Router** | Decides when to use tools, sub-agents, or respond directly |
| **Task Manager** | Tracks todos, progress, and completion |
| **Interrupt Handler** | Manages user interruptions and approvals |

### 4. Context Layer
Builds the optimal context for each model call.

| Component | Purpose |
|---|---|
| **System Prompt** | Agent identity, rules, capabilities |
| **Context Builder** | Assembles relevant files, history, memory |
| **Project Scanner** | Understands codebase structure |
| **Memory Retrieval** | Pulls relevant long-term memories |
| **Token Budget Manager** | Ensures context fits within limits |

### 5. Tool Layer
Enables the agent to take action in the environment.

| Component | Purpose |
|---|---|
| **Tool Registry** | Catalog of available tools with schemas |
| **Tool Executor** | Validates and executes tool calls |
| **Permission Checker** | Enforces allowlists/denylists/approvals |
| **Sandbox** | Isolates potentially dangerous operations |
| **Result Formatter** | Normalizes tool results for the model |

### 6. Model Layer
Handles communication with LLM providers.

| Component | Purpose |
|---|---|
| **Model Client** | Unified interface to multiple providers |
| **Message Formatter** | Converts internal state to provider format |
| **Streaming Handler** | Processes streaming responses |
| **Rate Limiter** | Manages API rate limits |
| **Retry Logic** | Handles transient failures |

### 7. Environment Layer
Interfaces with the outside world.

| Component | Purpose |
|---|---|
| **Filesystem** | Read, write, edit files |
| **Shell Executor** | Run commands with safety controls |
| **Git Integration** | Commits, branches, diffs |
| **Browser** | Web navigation and interaction |
| **MCP Client** | Connect to external MCP servers |
| **Network** | HTTP requests, API calls |

### 8. Observability Layer
Provides visibility into agent behavior.

| Component | Purpose |
|---|---|
| **Tracer** | Distributed tracing of agent steps |
| **Logger** | Structured logging |
| **Metrics** | Tokens, cost, latency, success rate |
| **Telemetry** | Usage analytics (if enabled) |
| **Debug UI** | Trace viewer, step inspection |

## Design Patterns

| Pattern | Description | Use Case |
|---|---|---|
| **ReAct Loop** | Reason → Act → Observe repeatedly | General purpose agents |
| **Plan-Execute** | Plan first, then execute steps | Complex multi-step tasks |
| **Tool-Use First** | Prioritize tool calls over long reasoning | Action-oriented tasks |
| **Sub-Agent Delegation** | Spawn specialized agents for subtasks | Parallel work, isolation |
| **Human-in-the-Loop** | Pause for approval on sensitive actions | Destructive operations |
| **Event-Driven** | React to events and tool results | Long-running workflows |

## Architecture Considerations

### Modularity
- Each component should be replaceable
- Clear interfaces between layers
- Plugin architecture for tools/extensions

### Extensibility
- Support custom tools easily
- MCP for third-party integrations
- Hooks/callbacks for customization

### Performance
- Parallel tool execution where safe
- Smart context pruning
- Streaming for responsiveness
- Caching where appropriate

### Security
- Principle of least privilege
- Sandboxing for shell/filesystem
- Secret management
- Audit logging

### Reliability
- Graceful error handling
- Checkpointing for long tasks
- Timeout management
- Cancellation support

## Example: Claude Code Architecture (Conceptual)

```
User Input → Session → Orchestrator
                        ↓
                    Context Builder (CLAUDE.md, files, history)
                        ↓
                    Model (Claude) with tools
                        ↓
                    Tool Executor (with permissions)
                        ├── Read/Write/Edit
                        ├── Bash (with approval)
                        ├── Grep/Glob
                        ├── Task (sub-agents)
                        └── MCP tools
                        ↓
                    Results → Context → Next iteration
```

## Building Blocks Checklist

When building a harness, you'll need:
- [ ] Agent loop implementation
- [ ] Tool registry and executor
- [ ] Permission system
- [ ] Context builder
- [ ] Model client abstraction
- [ ] State/checkpointing
- [ ] Filesystem and shell integration
- [ ] Error handling and recovery
- [ ] Observability
- [ ] UI/CLI interface

## Related Notes

- [[Agent-Loop.md]] — Deep dive into the agent loop
- [[../Core-Components/Tool-Registry.md]] — Tool system design
- [[../Core-Components/Permission-System.md]] — Safety mechanisms
- [[../Execution/Sub-Agents.md]] — Delegation patterns
- [[../Building-A-Harness/Minimal-Harness.md]] — Start building

## Sources

* Anthropic Engineering Blog  
* OpenCode Architecture (open source)  
* Claude Code documentation  
* LangGraph concepts  
* "Building an Agentic CLI" patterns