Cloudflare Agents 要升級 AI SDK 7 嗎？先對齊 ai 與 @ai-sdk/react 版本

先確認目前的版本組合#

Cloudflare 支援的 peer 版本可以先整理成這張表：

先在專案根目錄檢查實際解析到的版本，不要只看 package.json 的範圍：

1
pnpm list ai @ai-sdk/react agents @cloudflare/ai-chat @cloudflare/codemode @cloudflare/think --depth 0

如果輸出同時出現 ai@7 和 @ai-sdk/react@3，或反過來出現 v6 與 v4，就先修正版本組合，再處理其他 TypeScript 或 API 錯誤。peer dependency 警告不一定會立即讓建置失敗，但常常會在 hook 型別、訊息格式或串流事件處理時才暴露。

維持 v6 時怎麼升級 Cloudflare 套件#

既有專案若還沒有要改用 AI SDK v7，可以保留 v6，並把 Cloudflare 套件更新到支援雙版本的版本：

1
pnpm add agents@latest @cloudflare/ai-chat@latest \
2
  @cloudflare/codemode@latest @cloudflare/think@latest \
3
  ai@^6 @ai-sdk/react@^3

這條指令的重點不是追求所有套件都用相同版號，而是讓 ai 和 @ai-sdk/react 維持同一個 major。更新後應檢查 lockfile 是否把其他 provider、UI adapter 或自訂工具的 peer dependency 一起改掉。

如果專案已經有一篇 Cloudflare Agents 的 MCP SDK v2 遷移筆記，這次可以把 MCP 端點回歸和 AI SDK 升級分成兩個變更。兩者同時改動時，發生 tool call 錯誤會很難判斷是 transport、schema 還是 AI SDK 版本造成。

要升級 v7 時使用成對的指令#

Cloudflare 官方提供的 v7 安裝組合如下，使用 pnpm 時可以直接寫成：

1
pnpm add agents@latest @cloudflare/ai-chat@latest \
2
  @cloudflare/codemode@latest @cloudflare/think@latest \
3
  ai@^7 @ai-sdk/react@^4

完成後先檢查依賴樹：

1
pnpm list ai @ai-sdk/react agents @cloudflare/ai-chat @cloudflare/codemode @cloudflare/think --depth 0
2
pnpm install --lockfile-only

不要為了消除一個警告就把所有套件鎖成完全相同的版本號。Cloudflare 套件和 AI SDK 的發布節奏不同，應以 peer dependency 的 major 配對、lockfile 的可重現性與實際回歸結果為準。

Think：先測串流和 React 訊息層#

@cloudflare/think 的官方文件明確列出 v6、v7 的配對方式；升級 v7 後，最容易被忽略的是 server 端的串流事件與瀏覽器端 @ai-sdk/react hook 是否仍以相同格式接收訊息。

至少建立一條最小回歸流程：

1. 使用同一個 model 送出一般文字問題。
2. 讓 model 呼叫一個有輸入 schema 的 tool，確認參數與結果都能回到對話。
3. 中途刷新或重新連線，確認訊息不會重複或遺失。
4. 檢查 Durable Object 儲存的訊息與前端顯示順序一致。
5. 用瀏覽器的 Network 和 console 確認串流結束事件沒有變成錯誤。

如果只是更新依賴但沒有真的跑過瀏覽器端流程，TypeScript 通過不代表聊天體驗沒有回歸問題。Think 的價值在於替 agent 處理持久化、串流和工具迴圈，因此這些才是升級後應優先驗證的邊界。

Code Mode：工具執行與審批要分開測#

Code Mode 的 AI SDK 整合使用 @cloudflare/codemode/ai 把工具集合轉成 AI SDK tool。最小的 stateless 例子可以這樣保留在測試 Worker：

1
import { DynamicWorkerExecutor } from '@cloudflare/codemode'
2
import { createCodeTool } from '@cloudflare/codemode/ai'
3
import { generateText, stepCountIs } from 'ai'
4

5
const executor = new DynamicWorkerExecutor({ loader: env.LOADER })
6
const codemode = createCodeTool({ tools, executor })
7

8
const result = await generateText({
9
  model,
10
  prompt: '查詢目前狀態',
11
  tools: { codemode },
12
  stopWhen: stepCountIs(5),
13
})

升級時不要只測 generateText() 有沒有回傳文字，還要確認：

尤其要注意，官方 Code Mode 文件把 createCodeTool() 和 ToolSetConnector 的審批行為分開說明。不要把 stateless 工具執行時的「工具被過濾」誤認成 v7 破壞性變更；先確認你使用的整合模式。

升級失敗時先看哪一層#

可以按以下順序縮小問題：

1. peer dependency：確認 ai 與 @ai-sdk/react 是 v6/v3 或 v7/v4 的合法組合。
2. 型別與建置：檢查 import、tool schema 和 provider 的型別錯誤。
3. server 串流：確認 Worker 回應、WebSocket 或 stream event 沒有被轉成未處理例外。
4. client 渲染：確認 hook 使用的訊息型別、tool part 和 loading 狀態一致。
5. 平台行為：最後才檢查 Durable Object、Worker binding 或 Code Mode Loader。

這樣可以把套件版本問題和 Cloudflare 執行環境問題分開。如果你同時在升級 Workers 的 compatibility_date，也應把它獨立成另一個變更，避免一次引入兩組 runtime 差異。

結論：先選 major，再做功能回歸#

這次更新的重點是「雙版本相容」，不是要求所有 Cloudflare Agents 專案立刻改用 AI SDK v7。保留 v6 時使用 ai@^6 加 @ai-sdk/react@^3；升級 v7 時使用 ai@^7 加 @ai-sdk/react@^4，並一起檢查 Think、Code Mode、串流和工具審批。只要把版本配對與回歸範圍寫進升級清單，換 major 就不必變成一次盲目的全站重寫。

常見問題#