Pi

Pi ↗︎ is a minimal, extensible agent harness. The Agents SDK provides first-class support for building agents using the Pi harness, and this page shows how to run Pi Durable ↗︎ in a Cloudflare Durable Object with PiHarness from the Agents SDK.

Pi runs the agent loop: the transcript, the inbox of follow-ups and steers, model calls, tools, retries, and crash recovery. PiHarness gives Pi storage in the Durable Object's SQLite database, and wakes the object when Pi has work to finish.

Copy promptPrompt copied!

To start from a complete app, deploy the Pi harness example ↗︎. It streams sessions to a browser UI over WebSockets, and gives Pi a durable filesystem and JavaScript execution from @cloudflare/computer.

PiHarness is a new "Lifecycle capability" provided by the Cloudflare Agents SDK. Pi Durable provides the agent harness and the Lifecycle ↗︎ is responsible for keeping the agent running in the Durable Object. The Lifecycle is a core concept in the Agents SDK ensuring that long-running work can run in a Durable Object, surviving restarts, crashes, and network issues. A Lifecycle capability is a reusable piece of a Durable Object that the Lifecycle starts and gives SQLite storage and a durable job queue. PiHarness uses them in two ways:

• Storage. Pi keeps its transcripts, inbox, and tasks in its own tables in the object's SQLite database. The table names start with pi_, so they do not collide with your own tables.
• Wake-up. Pi's scheduler runs in memory, and an evicted object has none. PiHarness schedules one Lifecycle job for the object, driven by Pi's wake(). The job keeps a heartbeat while Pi works, is due when Pi's next sleeping task wakes, and completes when Pi has nothing to do. If the object is evicted mid-run, the job's alarm restarts it, Pi reopens its storage, and the run continues.

PiHarness does not choose how clients reach a session. It gives you each session's event stream, and you send it over WebSockets, HTTP, or RPC.

Install agents with Pi Durable, Pi AI, and Chord:

npm i agents @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord

yarn add agents @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord

pnpm add agents @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord

bun add agents @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord

The three Pi packages are optional peer dependencies of agents, at ~1.4.0. Pi Durable is experimental and its API can change in minor releases, so each agents release supports one Pi minor version. Agents SDK 0.30.0 and later support Pi 1.4.

The agents/models/pi-ai entry point supports AI Gateway and Workers AI models, so you can get started with Cloudflare models right away or use your existing Pi AI provider. The examples on this page use Workers AI through the AI binding and the Pi AI model provider. Add the binding and a SQLite-backed Durable Object to your Wrangler configuration:

{
	"name": "pi-agent",
	"main": "src/index.ts",
	"upload_source_maps": true,
	// Set this to today's date
	"compatibility_date": "2026-10-24",
	"compatibility_flags": ["nodejs_compat"],
	"ai": {
		"binding": "AI",
	},
	"durable_objects": {
		"bindings": [{ "name": "Assistant", "class_name": "Assistant" }],
	},
	"migrations": [{ "tag": "v1", "new_sqlite_classes": ["Assistant"] }],
}

name = "pi-agent"
main = "src/index.ts"
upload_source_maps = true
# Set this to today's date
compatibility_date = "2026-10-24"
compatibility_flags = [ "nodejs_compat" ]

[ai]
binding = "AI"

[[durable_objects.bindings]]
name = "Assistant"
class_name = "Assistant"

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "Assistant" ]

PiHarness is a Lifecycle capability, so it runs on a plain Durable Object. Open Pi's Harness in a factory, install a Lifecycle on the object, and add the harness to it:

import { DurableObject } from "cloudflare:workers";
import { createModels } from "@earendil-works/pi-ai/models";
import { createRegistry, Harness } from "@earendil-works/pi-durable";
import { PiHarness } from "agents/harness/pi";
import { Lifecycle } from "agents/lifecycle";
import { createAI } from "agents/models/pi-ai";

export class Assistant extends DurableObject {
	ai = createAI({ binding: this.env.AI });
	registry = createRegistry();

	harness = new PiHarness({
		harness: ({ storage, context, onWake }) => {
			const models = createModels();
			models.setProvider(this.ai.provider);
			return Harness.open(
				storage,
				{ models, registry: this.registry, onWake },
				context,
			);
		},
		defaults: { model: this.ai("@cf/zai-org/glm-5.3-flash") },
	});

	lifecycle = Lifecycle.install(this).use(this.harness);

	async ask(prompt) {
		const { text } = await this.harness.prompt(prompt);
		return text;
	}
}

export default {
	async fetch(request, env) {
		const agent = env.Assistant.getByName("demo");
		return Response.json({ text: await agent.ask("What is 47 × 19?") });
	},
};

import { DurableObject } from "cloudflare:workers";
import { createModels } from "@earendil-works/pi-ai/models";
import { createRegistry, Harness } from "@earendil-works/pi-durable";
import { PiHarness } from "agents/harness/pi";
import { Lifecycle } from "agents/lifecycle";
import { createAI } from "agents/models/pi-ai";

export class Assistant extends DurableObject<Env> {
	ai = createAI({ binding: this.env.AI });
	registry = createRegistry();

	harness = new PiHarness({
		harness: ({ storage, context, onWake }) => {
			const models = createModels();
			models.setProvider(this.ai.provider);
			return Harness.open(
				storage,
				{ models, registry: this.registry, onWake },
				context,
			);
		},
		defaults: { model: this.ai("@cf/zai-org/glm-5.3-flash") },
	});

	lifecycle = Lifecycle.install(this).use(this.harness);

	async ask(prompt: string) {
		const { text } = await this.harness.prompt(prompt);
		return text;
	}
}

export default {
	async fetch(request: Request, env: Env) {
		const agent = env.Assistant.getByName("demo");
		return Response.json({ text: await agent.ask("What is 47 × 19?") });
	},
};

The harness factory receives storage, Pi's storage over the object's SQLite database, context, a background context for opening Pi, and onWake, so the object can hibernate while Pi's tasks sleep. Everything else that Harness.open() takes is yours to build in the factory: models, the registry of tools and prompt sections, settings, env, and onReport.

The factory runs inside the object's startup, before any session is used, and again whenever the harness reopens Pi after a storage error (refer to Recovery). Keep it safe to run more than once. If it throws, the operation that started it fails, and the next operation tries again. Every PiHarness operation waits for startup, so a call that arrives over RPC before startup does not open Pi on its own.

Without a model, a session's prompts end unanswered until you set one.

Settings for the whole harness go in Pi's settings, passed to Harness.open(). For example, settings: { retry: { enabled: true, maxRetries: 2, baseDelayMs: 500 } } retries a failed model request. compaction and toolExecution set how Pi compacts long transcripts and runs a round's tools.

Both tools and system prompt sections are provided to the Pi Harness via extensions. A Pi extension is a plain object with a name, tools, and sections. Install it on the registry you open Pi with:

import { Type } from "@earendil-works/pi-ai";
import type { ToolRegistration } from "@earendil-works/pi-durable";

const WordCount = Type.Object({ text: Type.String() });

const wordCount: ToolRegistration<typeof WordCount> = {
	name: "word_count",
	description: "Count the words in a text.",
	parameters: WordCount,
	replay: "safe",
	async execute({ text }) {
		const words = text.split(/\s+/).filter(Boolean).length;
		return { output: [{ type: "text", text: String(words) }] };
	},
};

this.registry.install({
	name: "editor",
	sections: [
		{ key: "preamble", render: () => "You are an editor.", tag: false },
	],
	tools: [wordCount],
});

For more information on creating and configuring extensions, including skills and replay safety, refer to Extensions.

harness.prompt() submits to the root session and waits for the answer. It returns the final assistant text, the status, and the session's transcript as messages.

For long runs, submit and wait separately. submit() returns once Pi has durably stored the input, before the model runs. wait() returns the result when Pi finishes:

const receipt = await this.harness.submit("Summarize the latest report", {
	operationId: "report-summary-42",
});

// Later, possibly from another request:
const result = await this.harness.wait(receipt.operationId);
// { operationId, session, status: "done" | "unanswered", text?, reason? }

An operationId makes a submission idempotent. Submitting the same id again returns the same operation with accepted: false. Use an id that survives your own retries, such as an inbound event id.

A submission made while the session is running is queued and answered after the current run, as its own run. Set whenBusy: "steer", or call session.steer(), to join the running work after its current tool round instead.

harness.pending() lists submissions Pi has not finished, with their status: queued, running, or parked. A submission is parked when Pi's restart limit stopped its work (refer to Recovery).

Pi records every submitted input as a pi.user entry, as if the user typed it. Your code often submits input of its own, such as a prompt from a scheduled job, a webhook payload, or the outcome of an approval. To record where that input came from, pass entry with a kind of your own and any data you want to keep with it:

await this.harness.submit("The deploy was approved. Run the migration.", {
	entry: { kind: "app.approval", data: { approved: true, by: "ben" } },
});

await this.harness.submit("The deploy was approved. Run the migration.", {
	entry: { kind: "app.approval", data: { approved: true, by: "ben" } },
});

The model sees no difference: it still gets the text as a user message. Only the transcript changes. The input is stored with your kind and data instead of pi.user, and messages() and events() return both, so your UI can show it differently, for example as "Approved by ben" rather than as something the user said. Pi reserves kinds that start with pi., so use a prefix of your own, such as app..

The kind is a label, not a permission. It records what your code said the input was, and nothing checks it. The model reads the input as if the user wrote it, so do not put anything in it that you would not let the user send.

A run fails with model_error when the model errors and Pi does not retry it, or the error outlasts Pi's retries. It fails with no_model when the session has no usable model. The run's own submission settles unanswered with that reason. Pi's settings.afterFailedRun decides what happens to the submissions queued behind it:

Set it in the factory:

harness: ({ storage, context, onWake }) =>
	Harness.open(
		storage,
		{
			models,
			registry: this.registry,
			onWake,
			settings: { afterFailedRun: "withdraw" },
		},
		context,
	);

harness: ({ storage, context, onWake }) =>
	Harness.open(
		storage,
		{
			models,
			registry: this.registry,
			onWake,
			settings: { afterFailedRun: "withdraw" },
		},
		context,
	);

With keep, the kept submissions are not work for Pi, so the object can hibernate until the next submit() or reset(). Pass a signal to wait() if a caller should not wait that long. To withdraw a kept submission, call abort(operationId).

A session is a Pi conversation. The root session has the id "1" and exists from the start. The harness methods take an optional session option, and harness.session(id) returns a handle for one session:

const session = await this.harness.sessions.create();
await session.submit("Draft a release note");

const fork = await this.harness.sessions.fork(session.id);
const all = await this.harness.sessions.list();
// [{ id: "1", busy: false }, { id: "2", busy: true }, { id: "3", parent: "2", busy: false }]

sessions.create() makes a new top-level session with the harness defaults. sessions.fork(id) makes a session that sees another's history up to its newest entry. sessions.list() includes sessions that Pi's subagent tools created.

Session ids are Pi's conversation ids, so you cannot choose them. To give each user or chat its own agent, use one Durable Object per conversation and the root session in each.

session.events() returns Pi's AgentEventStream: a snapshot of the session, then one batch of events for each change Pi commits:

const stream = await this.harness.session().events();
send(stream.snapshot);

stream.start(async (events) => {
	for (const event of events) send(event);
});

// When the client goes away:
await stream.stop();

A client that connects mid-run gets a snapshot that includes the partial answer, then follows the live events. The stream lives in memory. After the object restarts, open a new stream and send a fresh snapshot.

messages() and snapshot.entries are Pi's transcript entries, not a chat UI format. Map them to what your client renders.

For anything PiHarness does not cover, await harness.pi() returns the opened Pi Harness.

Mark a tool replay: "safe" when running it twice is harmless, such as a read or a whole-file write. Leave other tools unsafe, such as an edit that would fail on text it already replaced, or a call that charges a card.

While Pi has work, the job's heartbeat alarm fires every 30 seconds. A crashed object restarts on the next heartbeat.

While Pi's tasks sleep, such as during a retry backoff, the job is due when the first one wakes. Pi reports when through the onWake callback that the factory passes to Harness.open(), and sets no in-memory timer, so the object can hibernate until then.

A task that keeps crashing the object would restart it forever. Pi parks a task that a crash or eviction cuts off settings.restartLimit times in a row (default 5) without progress. A parked task is not work, so the job completes and the object can hibernate. Its operations show as parked in pending(), and wait() keeps waiting. If the factory passes onReport to Harness.open(), Pi reports it there as task_parked. Once you have dealt with the cause, session.retry() runs it again. session.abort() gives up on it instead.

• Approvals. Pi Durable has no approval or permission step for tool calls yet.
• Event replay. Event streams always start from a snapshot. There is no cursor to resume a stream from.
• Abort and tools. abort() waits until the session is idle. A tool that ignores its abort signal keeps the session busy until it returns.
• Long model calls. The wake-up job waits inside an alarm invocation, and an alarm invocation runs for up to 15 minutes. The harness hands off to a new alarm every 10 minutes, but one model request that streams for more than 15 minutes can be cut off.
• Background tasks. Work that Pi runs in the background is checked on each heartbeat, so the harness notices it finish up to 30 seconds late.
• Graceful eviction. A running session keeps work in flight, so the object does not drain while Pi runs.
• Session deletion. Pi Durable cannot delete a conversation yet.