Agent Harness Engineering: The Runtime for AI Workers

1. The Agent Harness: What the Agent Factory Book Says

The AI Agent Factory framework defines the Agent Harness as the runtime that makes agents controllable and useful. The model is necessary, but it is not sufficient. In production, the model is simply one node in a larger governed execution environment.

The Agent Factory book describes the harness as the layer that defines:

What the agent knows (context construction and delivery)
What the agent can do (tool permissions and MCP interface)
What the agent cannot do (guardrails and policy enforcement)
How the agent's work is verified (maker-checker, evals, trace inspection)
What happens when something goes wrong (error classification, recovery, escalation)

graph LR
    subgraph Harness[Agent Harness Runtime]
        IC[Identity Config]
        CL[Context Loader]
        SL[Skill Loader]
        TE[Tool Executor MCP]
        PG[Policy Guard]
        CP[Checkpoint State]
        TR[Trace Emitter]
    end
    LLM[LLM Reasoning Loop] <--> Harness
    Harness --> Output[Typed Observable Output]
    Output --> Eval[Evaluation Layer]

2. The Loop Engineering Perspective

The Agent Factory crash course on Loop Engineering establishes that an agent is fundamentally a loop: it receives an input, reasons about what to do, invokes a tool or action, observes the result, and loops until the work is done or a stop condition is met.

The harness governs this loop. Without a harness:

The loop can run indefinitely (no stop conditions)
The loop can invoke any action without checking permissions
The loop can produce outputs that are never verified
The loop has no checkpoint mechanism if interrupted

The Loop Architecture

sequenceDiagram
    participant H as Harness
    participant L as LLM
    participant T as MCP Tool
    participant V as Verifier

    H->>L: Inject: Context + Active Skill + State
    L->>H: Tool call request: {tool, args}
    H->>H: Pre-call hook: validate args, check permissions
    H->>T: Execute tool (sandboxed)
    T->>H: Tool result
    H->>H: Post-call hook: validate output schema
    H->>L: Inject: updated state + tool result
    L->>H: Final output or next tool call
    H->>V: Submit output for verification
    V->>H: Verification result (pass/fail/escalate)

3. The Four Harness Responsibilities (Agent Factory Framework)

3.1 Context Management & Injection

The harness owns what goes into each model call. It:

Resolves which SKILL.md procedures to load for the current task
Injects the current agent state (what has been done, what is pending)
Applies token budget enforcement (prevents context overflow)
Filters retrieval results to only relevant domain knowledge

3.2 Tool Sandboxing via Model Context Protocol (MCP)

The Agent Factory book specifies that all tool access must flow through Model Context Protocol (MCP) servers. MCP is the wire between the agent's reasoning and the external world. The harness:

Maintains the MCP server registry
Enforces least-privilege access per tool call
Pauses execution for human approval on high-risk operations
Logs every tool invocation to a distributed audit trail

# OpenAI Agents SDK: require_approval pattern from Agent Factory
from agents import Agent, function_tool
from agents.approvals import require_approval

@function_tool
@require_approval  # Harness-level gate: human must approve before execution
async def execute_database_write(query: str, target_table: str) -> str:
    """Execute a write operation to the production database."""
    # This only runs after a human operator approves the queued action
    return await db.execute(query, target_table)

3.3 Execution Hooks (Pre-call and Post-call)

class ProductionHarness:
    async def before_tool_call(self, tool_name: str, args: dict, context: AgentContext):
        # 1. Schema validation
        validated_args = ToolArgSchema[tool_name].model_validate(args)
        
        # 2. Permission check
        if not context.permissions.allows(tool_name, args):
            raise PermissionDenied(f"{tool_name} requires {context.permissions.required_for(tool_name)}")
        
        # 3. Audit log
        await self.audit_log.record("TOOL_CALL_START", tool_name, validated_args)
        
    async def after_tool_call(self, tool_name: str, result: Any, context: AgentContext):
        # 1. Output schema verification
        if not ToolOutputSchema[tool_name].is_valid(result):
            raise OutputSchemaError(f"{tool_name} returned invalid schema")
        
        # 2. State checkpoint
        await self.state_store.checkpoint(context.run_id, context.current_step, result)
        
        # 3. Completion audit
        await self.audit_log.record("TOOL_CALL_COMPLETE", tool_name, result)

3.4 State Checkpointing & Recovery

Every step in an agent's workflow is checkpointed to a durable state store (Neon Postgres or Redis). If the MCP server goes down, if the LLM API times out, or if the execution environment crashes mid-task, the harness can restore the agent to its last verified state and continue from there.

This is why the Agent Factory book recommends Neon Postgres with pgvector as the canonical System of Record for AI Workers: it provides both relational state storage and vector search for context retrieval in a single durable store.

4. Personal Agent Harnesses: OpenClaw and Hermes

The Agent Factory book introduces two personal harness implementations:

OpenClaw: Built on Claude Code, the personal harness for autonomous coding and task execution with a local file system.
Hermes: A message-routing harness that manages context across multi-agent conversations.

Both harnesses follow the same principle: the agent body is separate from the agent intelligence. The harness defines what the agent can do. The model determines how it reasons about what to do within those boundaries.

5. Engineering Summary

The harness is not optional. Every production AI worker needs a governed execution runtime.
All tool access flows through MCP servers with least-privilege permissions.
Pre/Post hooks enforce schema contracts, audit everything, and enforce policy.
Durable state checkpoints (Neon Postgres) allow workers to recover from failures.
Personal harnesses (OpenClaw, Hermes) implement this pattern for individual developers.

The Agent Harness: Agent Factory's Blueprint for the Runtime that Makes AI Workers Controllable and Useful