Cloudflare released Agents SDK 0.33.0 on November 3, 2026, moving its Pi integration to Pi 1.5. For teams running assistants with saved conversations, the upgrade changes deployment recovery: returning to older application code can leave those conversations unreadable.
Cloudflare recommends rolling forward—deploying a fix that remains compatible with Pi 1.5—if the upgrade goes wrong. Its migration instructions apply to applications using the Pi integration, not every Cloudflare customer. The practical task is to prepare recovery before upgraded code writes production conversation data.
Choose a recovery path before deployment
PiHarness connects Pi’s conversation engine to a Cloudflare Durable Object’s SQLite database, which holds its persistent state. The underlying pi-durable component remains experimental, and Cloudflare supports one Pi minor version at a time, according to its version-pinned integration guide.
Pi 1.4 cannot read conversations written by Pi 1.5. The upstream changelog describes stored-state migration followed by a write in the newer format. Downloading a package is not the same as crossing that boundary; allowing the upgraded runtime to write existing conversations is consequential. Unreadable to an older runtime does not mean the history has been deleted.
Separately, Cloudflare’s Worker rollback documentation says switching back to older code leaves connected resources unchanged. Rolling back Worker code does not restore an older conversation format. Taken together, these rules mean a rehearsal that only proves the old code can start does not establish that it can recover an upgraded conversation.
Prepare a compatible Pi 1.5 roll-forward deployment and identify the storage it must read. If a storage restore is part of the fallback, assess it separately: Durable Object point-in-time recovery covers the entire SQLite database, including SQL and key-value data, within the preceding 30 days. It is unavailable in local development. Restoring an object can revert other application data too; it cannot be assumed to undo external actions. This is not a documented lossless Pi downgrade procedure.
Align the packages and tool schemas
First inventory uses of agents/harness/pi, agents/models/pi-ai and Pi tools—the integrations named in the release’s upgrade section. Establish which Durable Objects hold their conversations before choosing a rehearsal environment.
For agents@0.33.0, the published package metadata specifies four optional Pi peer dependencies at ~1.5.0: @earendil-works/pi-durable, @earendil-works/pi-ai, @earendil-works/pi-schema and @earendil-works/chord. Update the affected package set together and review the resolved lockfile. Use documentation pinned to this release.
Check schema imports as part of that change: pi-ai no longer exports TypeBox’s Type. Cloudflare documents either using pi-schema builders or importing Type directly from typebox. The pi-schema obj() builder rejects undeclared properties unless explicitly opened. See the release instructions for that distinction and the related guide to preserving custom tool checks in Pi 1.5 for validation rules that need separate attention.
Update how the application displays history
Replace session.events() with session.watch(). Render the initial watch.value and subsequent calls whose kind is value, rather than rebuilding the display from the removed event stream. The migration example shows this change.
The default view begins with the newest 50 entries, grows to 100 and then removes older entries from the view window. For a longer displayed history, use ConversationTranscript with session.entries() to retrieve earlier pages, as the pinned session guide describes.
This creates two different recovery questions. An older runtime unable to read migrated state has a compatibility problem. A new client showing only recent entries may need history paging. Paging addresses the second case, not the first; entries leaving the display window are not evidence of deletion.
Replace the old retry controls
Remove calls to retry() and handling of the parked status. Under the new recovery behavior, a tool call that reaches the restart limit returns an error to the model, while an interrupted model request reaching that limit ends its run unanswered with restart_limit. A tool error does not necessarily stop the whole run.
Show runFailure when a run ends without an answer. Determine idleness from live.run === undefined, not from whether the entire live-state object is empty: the Pi changelog says failure information now remains while idle.
After addressing the cause, session.continue() can start another run on the existing transcript without adding a user message. Handle a busy-session rejection and nothing_to_answer when the transcript already ends in an answer. The session contract also matters for queued follow-ups: the default afterFailedRun: "keep" policy can leave them waiting while the session is idle, without keeping the wake job active. Provide an explicit recovery or cancellation route instead of treating “idle” as “finished.”
Update monitoring alongside the interface. The release notes change onReport to a single report tagged by kind, rename session_failed to storage_failed, and replace task_parked with task_interrupted.
Rehearse with separate storage
Before exposing production conversations to the upgraded runtime, use an isolated non-production environment with representative pre-upgrade data. The following checks target the documented compatibility and recovery changes; use harmless stand-ins for tools that would otherwise take external actions:
Open an older conversation, run it with the upgraded software, then reopen it with the intended Pi 1.5 recovery deployment. Confirm that the required history remains readable.
Use a transcript longer than the default view window. Check earlier-page loading, reconnection and the display around resets or compaction.
Interrupt streaming and exhaust retries. Verify the displayed failure, queued follow-ups and continuation or cancellation controls; do not expect removed parked-task handling to recover them.
Review each tool’s replay policy. The harness recovery guide distinguishes tools safe to run again after interruption from unsafe calls reported as interrupted; do not make every tool replayable merely to complete the migration.
Decide what the interface promises about partial replies, too. Pi’s documented persistence setting batches streamed output with a default delay of 1,000 milliseconds; a crash can lose about that much of the stream. Setting settings.progress.persistWithinMs to 0 requests storage after each partial commit, increasing write frequency. It is not a guarantee against every form of data loss.
Before routing production conversations to Pi 1.5, verify that the compatible recovery deployment can read them and that the updated interface can show older history and resolve unfinished work.