用 @cloudflare/think 构建零样板聊天 Agent：Cloudflare Agents SDK 高阶封装实战指南

在 autoskills 仓库的 agents-sdk 技能包中，references/think.md 记录了一个尚处于实验阶段的重量级能力：@cloudflare/think。它是 Cloudflare Agents SDK 提供的更高层聊天 Agent 类，把streamText循环、工具执行（tool execution）与消息持久化（message persistence）全部内置，让你只需实现getModel()和getSystemPrompt()两个方法即可得到一个完整可用的对话 Agent。本文将以该文档为骨架，结合仓库内同一技能包的配套参考（configuration、streaming-chat、client-sdk、routing 等），完整还原 Think 的接入方式、生命周期钩子、子 Agent 机制、前端客户端与 AIChatAgent 的取舍，并补充底层原理与配置要点，帮助你在 Cloudflare Workers 上以最小代码量搭建生产可用的聊天应用。

Think 是什么：把「脏活」全部接管

传统上，用 Cloudflare Agents SDK 构建聊天 Agent 需要你手动编排 AI SDK 的streamText循环、把模型输出转成 UI 消息流、再自行把消息持久化到 SQLite（参考同目录 streaming-chat.md 中AIChatAgent.onChatMessage的手写实现）。@cloudflare/think改变了这一模式：

@cloudflare/think是一个更高层的聊天 Agent 类，为你处理streamText循环、工具执行和消息持久化。你提供getModel()和getSystemPrompt()，Think 负责其余一切。

也就是说，Think 把「框架流程」与「你的业务」彻底分离：

安装仅需一条命令：

npm install @cloudflare/think

由于 Think 本质上是聊天 Agent 的进阶形态，它同样依赖 Agents SDK 的 DO（Durable Object）与 SQLite 基础设施；在 autoskills 的检测体系中，只要项目中安装了agents包（见 README.md 的「Cloudflare Agents」检测项），就会触发安装本技能包，因此npm install agents是 Think 正常工作的前置条件，可用npm ls agents先确认是否已安装。

最小 Agent：20 行跑通一个聊天机器人

Think 的最小实现只需要继承Think<Env>并实现两个方法：

import { Think } from "@cloudflare/think"; import { createWorkersAI } from "workers-ai-provider"; import { routeAgentRequest } from "agents"; export class MyAgent extends Think<Env> { getModel() { return createWorkersAI({ binding: this.env.AI })("@cf/meta/llama-4-scout-17b-16e-instruct"); } getSystemPrompt() { return "You are a helpful assistant."; } } export default { fetch: (req, env) => routeAgentRequest(req, env) };

关键点逐一拆解：

• Think<Env>：泛型参数Env是你的 Worker 绑定类型（通常由wrangler types生成，见 configuration.md）。Think 内部已经为你实现了onChatMessage之类的聊天流程方法，你无需再触碰底层。
• getModel()：返回一个 AI SDK v5/v6 兼容的 model 实例。示例使用workers-ai-provider的createWorkersAI绑定 Workers AI 的AIbinding，直接调用@cf/meta/llama-4-scout-17b-16e-instruct模型——这样无需任何外部 API Key，全部走 Cloudflare 的 AI 网关计费。
• getSystemPrompt()：返回系统提示词字符串，等价于streamText中的system参数。
• routeAgentRequest(req, env)：Agents SDK 的标准路由入口，把/agents/my-agent/{instance-name}之类的请求路由到对应 DO 实例（URL 模式细节见 routing.md）。注意类名MyAgent在 URL 中会变成 kebab 形式my-agent，路由匹配时需精确对应。

Wrangler 配置：Think 需要experimental标志

Think 依赖实验性运行时特性，因此experimental兼容性标志是必选项，这一点与标准AIChatAgent（只需nodejs_compat）不同：

{ "compatibility_flags": ["nodejs_compat", "experimental"], "durable_objects": { "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }] }, "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }], "ai": { "binding": "AI" } }

配置要点：

• durable_objects.bindings：每个 Agent 类都必须有一个 DO binding，name与class_name需要与导出的类名严格一致，否则会出现 "Namespace not found" 错误（routing.md 明确指出了这一常见坑）。
• migrations：new_sqlite_classes声明新建的 SQLite 存储类。规则是永远不要修改旧迁移，新增 Agent 类时追加新 tag（如v2）。
• ai.binding：与getModel()中this.env.AI对应；本地联调时如需使用远程 Workers AI，可参考 configuration.md 中的建议，在.dev.vars或配置里加"remote": true。
• tsconfig 注意：切勿开启experimentalDecorators，它会破坏 Agents SDK 的@callable装饰器（该提示同样出现在 configuration.md 的「Key Rules」中，是全局性约束）。

自定义工具：Think 自动完成工具循环

Think 让你通过覆写getTools()来声明工具，之后工具调用、参数解析、结果回填模型全部由框架自动执行——你不再需要像AIChatAgent那样手动把tools塞进每次streamText调用：

import { tool } from "ai"; import { z } from "zod"; export class MyAgent extends Think<Env> { getTools() { return { getWeather: tool({ description: "Get weather", parameters: z.object({ city: z.string() }), execute: async ({ city }) => `72°F in ${city}` }) }; } }

这里的tool()与z均来自 Vercel AI SDK 生态：tool()用于定义工具元数据与执行函数，zod的z.object({ city: z.string() })负责声明参数 JSON Schema（同时为模型提供结构化输入约束）。description是模型决定何时调用工具的关键依据，务必写得语义明确。Think 还会把返回字符串（如"72°F in Beijing"）自动回注给模型继续生成回复，整个「请求工具 → 执行 → 反馈」的多轮循环对开发者完全透明。

另外值得注意的是，Think 内置了 Workspace、execute、browser 等开箱即用的工具（见下文的对比表），你可以把它们与getTools()中自定义的工具一起参与自动执行。

生命周期钩子：六阶段接管 Agent 行为

Think 通过一组生命周期钩子提供细粒度的定制点，下表完整覆盖了原文档定义的六个钩子：

beforeTurn是其中最灵活的钩子：它接收TurnContext并返回TurnConfig，可以针对不同场景切换模型。原文档给出的典型示例是续写轮次降级到便宜模型：

async beforeTurn(ctx: TurnContext): Promise<TurnConfig> { if (ctx.continuation) { return { model: cheaperModel }; } return {}; }

ctx.continuation为 true 表示当前是工具执行后的续写轮（continuation），此时回复通常较短，切换到成本更低的模型可以在不明显影响体验的前提下省钱；返回空对象{}则代表沿用默认配置。这种「按轮次动态路由模型」的能力，在纯手写的AIChatAgent.onChatMessage中是很难优雅实现的（那里模型在每次消息里写死，参见 streaming-chat.md）。

configureSession()与记忆系统对接时，可以结合 Agents SDK 的this.sqlAPI 自行存取会话数据（参考 state-scheduling.md 中的 SQL 用法），或接入 MCP 上下文提供器。

子 Agent：让 Specialist 各司其职

Think 支持通过subAgent()在 Agent 内部派生并驱动子 Agent，实现多角色协作（如把任务委派给专门的 Specialist）：

const child = this.subAgent(SpecialistAgent, "specialist-1"); await child.chat("Analyze this data...", (chunk) => { // stream callback });

• this.subAgent(SpecialistAgent, "specialist-1")：第一个参数是子 Agent 的类（同样继承自 Think 或 Agents SDK 的 Agent），第二个参数是子 Agent 的实例名。子 Agent 作为独立 DO 实例运行，拥有自己的状态与 SQLite 存储，天然隔离会话。
• child.chat(message, callback)：向子 Agent 发起一次对话，第二个参数是流式回调，每个 chunk 都会触发，可用于实时聚合子 Agent 的产出。

这一机制让「调度者 Agent + 专业子 Agent」的分层架构成为可能：主 Agent 负责意图理解与编排，各 Specialist 负责特定领域（数据分析、代码审查、搜索等），且每个子 Agent 的上下文相互隔离、互不污染。

客户端接入：与 AIChatAgent 完全相同的 React Hooks

Think 的客户端 API 与AIChatAgent完全一致，意味着你可以直接复用 client-sdk.md 与 streaming-chat.md 中介绍的前端模式：

const agent = useAgent({ agent: "MyAgent", name: "session-1" }); const { messages, input, handleInputChange, handleSubmit } = useAgentChat({ agent });

• useAgent（来自agents/react）：建立与/agents/my-agent/session-1的 WebSocket 连接，返回agent句柄。它同样支持onStateUpdate同步状态、onIdentity回调，以及query/queryDeps做查询参数鉴权（完整选项见 client-sdk.md）。
• useAgentChat（来自@cloudflare/ai-chat/react）：封装聊天输入输出，返回messages、input、handleInputChange、handleSubmit、status等。status取值包括ready/streaming/submitted/error（streaming-chat.md 有完整状态表）。
• 消息持久化与可续流：Think 内置消息持久化，流式 chunk 在传输过程中缓冲进 SQLite；客户端断线重连后，缓冲的 chunk 会立即补发，再继续实时流（AIChatAgent的这一行为默认开启，Think 同样继承）。

如果项目不使用 React，还可以用agents/client的AgentClient（vanilla JS）或agentFetch（纯 HTTP）对接 Think Agent 的可调用方法。

Think vs AIChatAgent：何时选哪个

选择建议：

• 选 Think：当你的场景是「标准的多轮对话 + 工具调用」，希望以最少样板代码快速上线，且能接受experimental标志与 API 可能变动的实验性质。Think 的钩子体系（beforeTurn动态换模型、onChatResponse链式编排）让多数常见定制无需触碰底层流。
• 选 AIChatAgent：当你需要对每次 LLM 调用的输入输出做精细控制（例如自定义流式协议、特殊的多模型路由、深度定制 UI 消息流），或者你正在使用标准的nodejs_compat配置、不想引入实验性依赖。AIChatAgent 的完整手写范式见 streaming-chat.md（其中还包括createUIMessageStream的自定义流方案与messageConcurrency、chatRecovery、maxPersistedMessages等关键属性）。

此外需要留意：Think 属于实验性能力，与本技能包中 Voice（@cloudflare/voice）、Codemode、Browse the web 等并列，均标注为 experimental（见 SKILL.md 的能力清单），升级@cloudflare/ai-chat到 AI SDK v5/v6 时同样需要关注其兼容性。

小结与阅读延伸

@cloudflare/think的意义在于把 Cloudflare Agents SDK 聊天能力封装到「实现两个方法即可用」的极致：模型（getModel()）、系统提示（getSystemPrompt()）与工具（getTools()）是你的全部业务输入，streamText循环、工具执行循环、SQLite 消息持久化、可续流传输与 React 客户端集成全部内置。对于需要细粒度行为控制的场景，六阶段生命周期钩子与子 Agent 机制提供了足够的扩展深度。

想深入掌握本文涉及的底层机制，可以继续阅读本技能包内的相关参考：

• references/streaming-chat.md — AIChatAgent 手写范式、可续流原理与useAgentChat状态机
• references/client-sdk.md —useAgent/AgentClient/agentFetch的完整客户端 API
• references/configuration.md — wrangler.jsonc 完整配置、Vite 集成与类型生成
• references/routing.md — URL 路由模式与routeAgentRequest选项
• references/state-scheduling.md — 状态管理、SQL API 与调度能力
• SKILL.md — Agents SDK 全量能力地图与安装校验

提示：Think 仍为实验性 API，生产环境使用前请确认所选 Agents SDK / AI SDK 版本对该特性的支持状态，并保留experimental兼容性标志的升级预案。