Harness Design Pattern

A harness is the scaffolding that wraps a model (e.g. Claude) and implements the agentic loop: it assembles prompts, calls the model, dispatches tool calls, and manages conversation state.

The core problem

"Harnesses encode assumptions that go stale as models improve."

When the harness runs inside the execution container, changing the model or loop logic requires redeploying the container. Model capabilities evolve faster than infrastructure, so tightly coupled harnesses become a liability.

The pattern: harness outside the container

Move the harness out of the execution environment. The harness interacts with containers through a minimal interface:

execute(name, input) → string

The container becomes a dumb executor. The harness becomes portable and model-upgradeable without touching execution infrastructure.

Benefits

• Container failures are just errors. They propagate as strings to the model, which can decide to retry — no special recovery logic needed in the harness.
• No container nursing. Previously, container failures required complex health-check and restart logic. Now that's gone.
• On-demand provisioning. Containers don't need to stay alive between tasks. Spin up per-call, tear down after. This delivered 60–90%+ time-to-first-token improvements.
• Credential isolation. Credentials are never in scope of the sandbox where model-generated code runs.

Relationship to session durability

The harness is now stateless relative to the session — all conversation state lives in the session log. On crash:

1. New harness instance starts.
2. Calls wake(sessionId) + getSession(id).
3. Resumes from last event — no state loss.

Comparison

Related

• Managed Agents Architecture — full three-layer model
• Durable Session Storage — stateless harness depends on external session
• Agent Loop (OpenClaw) — compare: OpenClaw's harness runs embedded in pi-agent-core