Harnesses

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

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.

To build a new agent, start with the Pi harness, which runs Pi Durable in a Durable Object. You can also run OpenCode, or build the loop yourself on top of the Agents SDK runtime.

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. Think and AIChatAgent install the SDK's Sessions capability. To find the APIs relevant to your agent, refer to Choose capabilities.

Use Pi when you want Pi Durable ↗︎ to own the agent loop, transcript, and recovery. This is the recommended starting point for a new agent. PiHarness runs Pi in a Durable Object and wakes it after eviction. You choose the transport.

Use a build-your-own harness when you need full control over the model call, message format, tool loop, or UI protocol. This is the right approach when you want to compose low-level APIs directly from the Agents SDK.

Use OpenCode (experimental) when you want OpenCode 2.0's sessions, tools, and plugin system. OpenCodeHarness runs OpenCode's Workerd SDK ↗︎ inside a plain Durable Object.

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.