How to migrate Agents SDK v0.33.0 to Pi 1.5

This is a migration guide based on the changelog and official documentation consulted on November 4, 2026. We did not run the upgrade or the examples in this review.

In this article you will see:

• What changes arrive with Agents SDK v0.33.0 and Pi 1.5.
• How to locate calls and states that need to be migrated.
• How to adapt session tracking and continuation of an execution.
• Why transcript compatibility requires planning the rollback before the update.

Agents SDK v0.33.0 updates PiHarness for Pi 1.5

PiHarness connects the Pi Durable agent to Cloudflare's Agents SDK and uses the Durable Object's SQLite storage to preserve session state. Version v0.33.0 updates this integration to Pi 1.5.

Cloudflare reports fewer storage writes during response streaming and lower memory usage on large tool calls. In its tests, it reports 27 times fewer transactions for long responses and 5.7 times fewer on turns with parallel tool calls.

Under a load with 2,048 sessions, the team reports throughput from 88 to 459 executions per second. These numbers describe Cloudflare's test. They do not guarantee the same gain in any application, account, hardware or usage pattern.

The change also adds a path to continue a conversation without attaching a new user message. This helps when an execution ends without a response, for example after a model error, but requires the session to be idle.

Prepare the migration to Pi 1.5 before updating

Start by identifying which version of Agents SDK and Pi Durable the project uses today. Also record how the application stores transcripts and how the client tracks the response while it is being generated.

Make a test copy of the data and run the migration in a separate environment before changing an installation used by customers. This is an engineering precaution to reduce the impact of incompatible changes, not a guarantee published by Cloudflare.

Then follow the official instructions in the Agents SDK v0.33.0 changelog. The documentation recommends replacing calls to session.events() with session.watch() and removing dependencies on retry() and status parked.

session.watch() delivers the current view of the session, including recent transcript entries and live state, such as streaming response, tools running and reason an execution ended without a response. The documentation shows starting and updating the monitor like this:

const watch = await this.harness.session().watch();
render(watch.value);

watch.start(async (call) => {
  if (call.kind === "value") render(call.value);
});

The code illustrates the documented format, it was not executed in this review. The application also needs to close the monitor when the client disconnects and handle carefully a reconnection after the object restarts.

Remove the old retry and parked states

The previous flow could park a task that failed repeatedly and expose the state parked. Pi 1.5 removes retry() and that status. A task that reaches the restart limit ends instead of remaining parked.

Before upgrading, search for uses of those names in code and tests. Replace the old logic with the result handling that the new version offers, instead of removing the condition without defining what the interface should show the user.

For an existing execution, Cloudflare documentation shows checking the result and continuing after model_error using another operationId:

const result = await session.wait(operationId);
if (result.status === "unanswered" && result.reason === "model_error") {
  const receipt = await session.continue({
    operationId: `${operationId}:continue`,
  });
  const continued = await session.wait(receipt.operationId);
  console.log(continued.status, continued.text);
}

continue() starts a new execution without adding a user message. The session needs to be idle. If the transcript already ends with a response, the operation returns unanswered with reason nothing_to_answer.

Plan a roll-forward because Pi 1.4 cannot read Pi 1.5 conversations

The most important caveat of the update is storage compatibility. After a conversation is run in Pi 1.5, Pi 1.4 cannot read it.

Therefore, Cloudflare recommends fixing problems by advancing the version, not rolling back to Pi 1.4. Before deploy, define how to disable the new version without reopening incompatible transcripts and how to keep an isolated test deployment.

A validation plan should cover, at minimum, a short response, a tool call, a model failure and client reconnection during a session. Record the saved state and visible result in each scenario.

The roadmap connects to practices already described on the blog, such as automate repository tasks with GitHub Agentic Workflows and organize agent sessions in VS Code 1.145. In both cases, reviewing the flow and effects is part of the work, not an optional detail.

Measure your flow without promising Cloudflare's numbers

Cloudflare's data explains why the team updated persistence and memory usage. They do not replace a measurement in your workload, because response duration, number of tools and concurrency can be different.

Before and after migration, compare the same set of tasks and record time to first response, total time, failures, memory usage and persisted reads or writes. Separate results by session type to avoid a small load hiding regressions in long calls.

The current documentation for PiHarness for Cloudflare Agents describes session.watch() and the new continuation path. Check it alongside the changelog before adapting the exact signature to your code.