Cloudflare Agents SDK + AI SDK v7: a safe package-pair migration checklist
Quick answer
Cloudflare announced on July 23, 2026 that its agents, @cloudflare/ai-chat, @cloudflare/codemode, and @cloudflare/think packages support both AI SDK v6 and v7. That is a compatibility release, not a reason to run a broad dependency refresh. Start by choosing one matching pair: AI SDK v6 with @ai-sdk/react v3, or AI SDK v7 with @ai-sdk/react v4. Then upgrade the Cloudflare packages, test one real agent path, run a small canary, and keep the previous lockfile ready to restore.
The important unit is the package pair plus a verified behavior—not the number in package.json. A green install only says that a peer range resolved. It does not prove that streaming, tool completion, telemetry, or your client UI still behave as users expect.
Who this is for
This checklist is for an indie developer or a small team that already has a Cloudflare Agents application using the AI SDK, especially @cloudflare/think, @cloudflare/ai-chat, or @cloudflare/codemode. It is not a generic migration guide for every Vercel AI SDK application, and it does not claim that AI SDK v7 changes Cloudflare Agents APIs.
If your agent connects to MCP servers, keep that boundary explicit during the upgrade. The MCP stateless migration checklist covers request-level compatibility; this page is about dependency pairing and a safe application rollout.
What changed—and what did not
Cloudflare's release says existing apps may stay on v6 while updating the listed Cloudflare packages, or adopt v7 without changing the Cloudflare Agents APIs they use. The supported peer ranges are ai@^6 || ^7 and @ai-sdk/react@^3 || ^4. Cloudflare explicitly pairs v6 with React package v3, and v7 with React package v4. It also says Think normalizes streaming, tool-completion events, and telemetry across those two AI SDK versions.
That tells you the supported version contract. It does not validate your custom tool UI, provider adapter, persisted session state, or deployment configuration. Treat each of those as an application-owned acceptance criterion.
Choose one migration lane
Do not let a package manager independently choose a mixed pair. Make the intended lane reviewable before you change anything.
| Lane | ai |
@ai-sdk/react |
When to use it | First risk to test |
|---|---|---|---|---|
| Stabilize | ^6 |
^3 |
You need current Cloudflare package fixes without a client-major migration | Existing stream rendering and tool UI remain unchanged |
| Migrate | ^7 |
^4 |
You deliberately need AI SDK v7 in this app | Package lock resolves one intended pair and the user-facing agent flow still completes |
| Stop | mixed or implicit | mixed or implicit | A transitive update selected incompatible majors | Do not deploy; pin the pair and inspect the lockfile |
For the v7 lane, Cloudflare provides this installation shape:
npm i agents@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/think@latest ai@^7 @ai-sdk/react@^4
Use only the packages your application actually imports. Adding every package from the example is unnecessary surface area. Commit the changed manifest and lockfile together so that the intended peer contract can be reviewed and restored as one change.
Run four gates before a production rollout
1. Resolve gate
Install from a clean working tree or CI job. Confirm that the resolved ai and @ai-sdk/react majors match the selected lane, and record the command plus the lockfile diff. If a workspace uses multiple package managers or lockfiles, stop and make that ownership clear before calling the result reproducible.
2. Agent-path gate
Exercise one smallest useful conversation: submit a prompt, receive a streamed response, run one non-destructive tool, render the tool result, and complete the turn. This targets the release's explicitly normalized boundaries—streaming, tool completion events, and telemetry—without pretending to benchmark model quality.
Use a sandbox or a read-only tool. The untrusted repository sandbox checklist remains relevant: a dependency upgrade does not make an agent safe to give write, deploy, or secret access.
3. Negative gate
Deliberately remove or delay one tool result in a test environment. The UI should show a useful failure state, not silently mark the agent turn complete. Also test a rejected approval if your app uses protected actions. Cloudflare's adjacent Code Mode update exposes requiresApproval for protected connector methods; preserve your own approval path rather than treating a successful import as a policy decision.
4. Canary gate
Send a small, observable slice of traffic or one internal workspace through the selected lane. Compare completion rate, stream interruption count, tool-result render failures, and operator-visible errors against the baseline. A canary is successful only when the evidence is comparable, not merely because it received a few prompts.
Copyable migration record
Keep a short record next to the dependency change. This is a team operating template, not a Cloudflare configuration schema.
agent_sdk_upgrade:
lane: "ai@^7 + @ai-sdk/react@^4"
cloudflare_packages: ["agents", "@cloudflare/think"]
before_merge: ["clean install", "lockfile peer-major check", "stream + tool-path test"]
canary: "one internal workspace or low-risk traffic slice"
compare: ["completion rate", "stream interruptions", "tool render errors", "telemetry errors"]
never_expand: ["tool permissions", "production deploy access", "secret access"]
rollback: "restore the previous manifest and lockfile, then redeploy the prior artifact"
promotion_gate: "all four gates have recorded evidence and no unexplained regression"
The template deliberately separates software compatibility from agent authority. A clean migration is not approval to broaden tool permissions or to make an autonomous workflow more aggressive. The same separation helps when you later fan out work across agents: Grok Build Workflows still needs independent verification and bounded scope.
Common mistakes
Upgrading only ai. The official compatibility statement names a matching @ai-sdk/react major. Keep the pair intentional instead of trusting an accidental transitive resolution.
Testing only a text response. A text-only smoke test misses the boundaries most likely to regress in an agent product: streaming, tool completion, and the UI state around them.
Calling a package upgrade a model evaluation. This release preserves an agent integration contract; it does not establish that any model is faster, cheaper, or more accurate for your workload. Use separate, task-based evidence for model choices.
Mixing the rollout with permission changes. A new version is already one variable. Keep MCP catalog changes, deploy access, and destructive actions out of the same canary.
FAQ
Can I update Cloudflare Agents packages and remain on AI SDK v6?
Yes. Cloudflare says existing applications can remain on v6 while updating the supported packages. Keep ai@^6 paired with @ai-sdk/react@^3, then verify your own agent path.
What is the v7 React package pairing?
Cloudflare documents ai@^7 with @ai-sdk/react@^4. Make that pair explicit in the manifest and lockfile rather than allowing a mixed major combination.
Does this release remove the need to test streaming and tools?
No. Cloudflare says Think normalizes streaming, tool completion events, and telemetry across v6 and v7. Your application still owns its UI behavior, provider integrations, permissions, and production acceptance criteria.
Top comments (0)