Skip to content

Harnesses

Last updated View as MarkdownAgent setup

A harness is the loop that makes an agent behave like an agent instead of a single model call.

For what a harness does and how to choose one, refer to Harness in Concepts.

It is responsible for the turn-by-turn work around the model: building the prompt, loading memory, selecting tools, handling tool results, streaming responses, persisting messages, and deciding whether the agent should continue or stop.

Most people building new agents should start with the Pi harness. To explore other approaches, compare where each harness runs, how it recovers, and how it accesses files.

How harnesses fit with the Agents SDK

Harnesses sit on top of the Agents SDK runtime:

  • The runtime coordinates startup and durable jobs, routing, and the capabilities you install. These can add WebSocket connections, shared state, scheduling, and MCP connections. Use observability to trace model calls and inspect runtime events.
  • The harness gives the agent behavior: model calls, prompt construction, tool selection, stream handling, memory strategy, and lifecycle hooks.

The runtime answers “where does this agent live and how does it stay durable?” The harness answers “what does this agent do on each turn?”

Conversation storage depends on the harness. Pi and OpenCode manage their own transcripts. Claude Code and Codex keep their records in a SQLite-backed HarnessStore. Think and AIChatAgent install the SDK's Sessions capability. To find the APIs relevant to your agent, refer to Choose capabilities.

Compare harnesses

Durability means the harness saves agent progress and can resume work after a crash, restart, or deployment. For SDK integrations, Lifecycle coordinates startup and recovery jobs.

Cloudflare Computer provides persistent files and file tools for agents. Agents can return to files they created or edited across turns, even after a restart.

Harness Runs in Durability Cloudflare Computer
Pi Durable Objects via the Agents SDK 🟢 Automatically resumes interrupted work 🟢 Supported
Flue ↗︎ Durable Objects via the Agents SDK 🟢 Automatically resumes interrupted work 🟢 Supported
OpenCode Durable Objects via the Agents SDK 🟡 Resumes interrupted work 🟡 Example plugin
Claude Code (Experimental) Linux container driven by a Durable Object via the Agents SDK 🟡 Reattaches after object restart; container loss fails or retries the turn 🔴 No built-in integration
Codex (Experimental) Linux container driven by a Durable Object via the Agents SDK 🟡 Reattaches after object restart; container loss fails or retries the turn 🔴 No built-in integration
Think (Experimental) Durable Objects via the Agents SDK 🟡 Continues from saved output 🟢 Supported
Nanocode (Pre-1.0) Wasm in its own Durable Object host 🟡 Resumes turns; some tools cannot recover 🟡 Custom adapter needed
Exo (Pre-1.0) Wasm in Durable Objects + Linux sandbox 🟡 Resumes turns; interrupted tools may fail 🔴 No integration
Self-modifying (Experimental) Durable Objects via the Agents SDK + Dynamic Workers 🟡 Resumes turns; custom tools may rerun 🟡 Workspace in example
Coding agent CLIs without a harness Linux sandbox 🔴 No automatic recovery in these examples 🔴 No integration

Choose an approach

Use Pi when you want Pi Durable to own the loop, transcript, and recovery. Use OpenCode for OpenCode's sessions, tools, and plugins, or Think for an AI SDK chat agent with built-in Workspace tools.

Use Flue ↗︎ for a TypeScript hooks API built on Pi, with automatic recovery and a Cloudflare target ↗︎ that uses the Agents SDK.

Use Claude Code or Codex to run those CLIs with their native tools, plugins, and settings in a Linux container. A Durable Object stores sessions and coordinates recovery. Container loss fails the interrupted turn by default. Optional retry reruns it. Workspace recovery uses filesystem snapshots, so edits since the last snapshot can be lost.

Build your own harness when you need control over model calls, message formats, or tool execution. Compose it from the Agents SDK runtime capabilities.

Explore the experimental self-modifying example for an agent that edits its own TypeScript harness.

Nanocode and Exo provide their own runtimes for running agents on Cloudflare.

What a harness usually owns

A harness usually owns:

  • Prompt construction — system prompts, memory, retrieved context, and per-turn instructions.
  • Model execution — the call to Workers AI, OpenAI, Anthropic, Gemini, or another provider.
  • Tool orchestration — server tools, client tools, MCP tools, approval flows, and continuation after tool results.
  • Message persistence — how user, assistant, and tool messages are saved and replayed.
  • Streaming and recovery — how responses stream to clients and resume after disconnects or Durable Object eviction.
  • Extension points — hooks before and after turns, steps, tool calls, and recovery events.

Agents SDK runtime

Compose a harness on a Durable Object with Lifecycle and optional capabilities.

Sessions

Store conversation context and memory across turns.

Was this helpful?