Harness Architecture

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

High-Level Architecture

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

Agent Loop — Deep dive into the agent loop
Tool Registry — Tool system design
Permission System — Safety mechanisms
Sub Agents — Delegation patterns
Minimal Harness — Start building

Sources

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

From the Agentic Engineering research vault · CC BY 4.0 · all notes · raw markdown