A Two-Stage Upgrade Plan for Cloudflare Agents SDK and AI SDK 7

The release gives you a rollback boundary, not a free migration

The useful change is separation. On July 23, 2026, Cloudflare made the current agents, @cloudflare/ai-chat, @cloudflare/codemode, and @cloudflare/think packages compatible with both AI SDK 6 and AI SDK 7. Existing applications can update those Cloudflare packages while staying on AI SDK 6, and Cloudflare says the later AI SDK 7 move does not require changes to the Cloudflare Agents APIs.

That does not make AI SDK 7 a drop-in dependency bump. It gives you a clean way to prove which layer caused a regression.

Cloudflare's compatibility announcement also says Think normalizes streaming, tool completion events, and telemetry across both versions. Treat that as an adapter guarantee, not proof that your application code has identical semantics. AI SDK 7 changes its runtime floor, prompt handling, stream callbacks, telemetry registration, and multi-step result shapes.

Stage one updates Cloudflare while AI SDK 6 stays pinned

The first deployment should change the Cloudflare layer and nothing else. Keep the AI SDK dependency pair explicit so a lockfile refresh cannot pull the application across the major-version boundary.

npm i agents@latest @cloudflare/ai-chat@latest \
  @cloudflare/codemode@latest @cloudflare/think@latest \
  ai@^6 @ai-sdk/react@^3

This stage needs behavioral evidence because Cloudflare chat agents are stateful. AIChatAgent automatically persists messages to SQLite, streams resume when a client disconnects and reconnects, and tool calls can cross the server and client boundary. A green typecheck does not exercise any of those paths.

For a platform engineer operating a customer-facing chat agent, the most valuable fixture is not a fresh greeting. It is an existing conversation that reconnects during a tool call, completes the tool once, and persists the final assistant message once. That single path crosses storage, streaming, tools, and client reconciliation.

Stage two moves the runtime and prompt contract to AI SDK 7

The AI SDK 7 change begins only after the Cloudflare baseline is stable. Its official migration guide provides a codemod, but explicitly warns that automated transforms may not cover every required change.

Start with the runtime contract. AI SDK 7 requires Node.js 22 or later, all AI SDK packages are ESM-only, and require() is no longer supported.

{
  "type": "module",
  "engines": {
    "node": ">=22"
  }
}

Then move the dependency pair and run the official codemod:

npm i agents@latest @cloudflare/ai-chat@latest \
  @cloudflare/codemode@latest @cloudflare/think@latest \
  ai@^7 @ai-sdk/react@^4

npx @ai-sdk/codemod v7

If the application exports OpenTelemetry traces, install the package that now owns the integration:

npm i @ai-sdk/otel

The dangerous changes are semantic, not syntactic.

Move trusted instructions out of persisted messages

AI SDK 7 renames the top-level system option to instructions. The old option remains as a deprecated fallback, but instructions wins when both are present. More importantly, system-role entries inside prompt or messages are rejected by default.

That is the migration trap for a Cloudflare chat agent with old conversations in SQLite. Do not bulk-enable allowSystemInMessages: true across user-editable history. The vendor limits that escape hatch to trusted messages because a writable system entry can replace the server's instruction boundary.

const result = streamText({
  model,
  instructions: trustedServerInstructions,
  messages: userAndAssistantMessages,
});

Normalize persisted histories at the application boundary: extract or discard trusted legacy system entries, keep user and assistant content as messages, and supply the current server-owned policy through instructions. Preserve the original record for audit, but do not pass untrusted system entries back into inference.

Re-test every prepareStep override

AI SDK 7 carries instructions returned by prepareStep into future steps until another override replaces them. Messages returned by prepareStep also become the base for subsequent steps. AI SDK 6 applied those overrides only to the current step.

If a support agent temporarily switches into a terse tool-selection instruction and expects the following answer to return to the default policy, that assumption is now wrong. Return the intended instruction for every branch, then replay a turn that crosses each branch. This is behavior a codemod cannot infer from the code shape.

Streaming and observability need semantic parity, not a green build

Stream handlers and cost dashboards can remain syntactically valid while changing meaning. AI SDK 7 calls onChunk for every TextStreamPart, including lifecycle, boundary, terminal, abort, and error parts. A handler written for the narrower AI SDK 6 callback can double-count work or assume every chunk contains text.

Guard on the event type before processing:

const result = streamText({
  model,
  instructions: trustedServerInstructions,
  messages,
  onChunk({ chunk }) {
    if (chunk.type !== "text-delta") return;
    textBuffer.append(chunk.text);
  },
});

The full event stream also moves from fullStream to stream, with the old property retained as a deprecated alias. Migrate the name, but test the consumer against start, tool, finish, abort, and error paths rather than only text deltas.

Telemetry needs a separate diff. OpenTelemetry span collection moved into @ai-sdk/otel and must be registered globally. Once an integration is registered, AI SDK 7 emits telemetry by default; AI SDK 6 required per-call opt-in. The option name also moves from experimental_telemetry to telemetry, while the old name remains as a deprecated alias.

The failure mode is an observability bill or cardinality jump, not a compile error. Compare event volume by operation, confirm sensitive prompt and response bodies remain excluded by your policy, and verify that turn, step, model, tool, and error identifiers still join into one trace.

Token accounting changes too. Top-level usage now totals every step, while finalStep.usage gives the former final-step-only view. Top-level content, tool calls, tool results, files, sources, and warnings also accumulate across all steps. Update dashboards and callbacks before comparing the new totals with the old field.

If model routing or provider failover is already changing, keep that work out of this migration as well. Use the AI gateway decision guide to scope it as its own boundary.

The decision rule is urgency versus isolation

Stay on AI SDK 6 after the Cloudflare update when the current application is stable and no AI SDK 7 capability justifies the migration risk. Cloudflare now supports that choice explicitly.

Move to AI SDK 7 when first-class tool approvals, durable WorkflowAgent execution, timeout controls, or the newer telemetry lifecycle materially solve a problem you own. Even then, migrate for parity first. Add the new capability in the following change, after old transcripts, multi-step prompts, stream consumers, traces, and usage reporting have passed.

For a funded product team, the key control here is not another approval screen. It is the rollback boundary between framework and SDK. Keep that boundary clean and every failure has a smaller search space.

Frequently asked questions