【免费下载链接】autoskillsOne command. Your entire AI skill stack. Installed.项目地址https://gitcode.com/gh_mirrors/au/autoskills点击查看免费下载本篇技术指南围绕 autoskills 仓库中agents-sdk技能所沉淀的官方参考文档 state-scheduling.md 展开系统讲解在 Cloudflare Workers 上构建有状态 AI Agent 的两大核心能力状态管理SQLite 持久化、自动广播、校验钩子与任务调度延迟、定点、Cron、固定间隔四种模式。读完本文你将能独立实现一个类型安全、可持久化、可实时同步、可定时唤醒的 Agent 实例并掌握setState/validateStateChange/this.schedule/scheduleEvery等核心 API 的完整用法与执行语义。前置准备让 Agent 拥有 SQLite 与调度能力状态与调度的底层依赖 Durable Objects 与 SQLite因此在写任何状态代码之前必须先完成wrangler.jsonc配置。参考 configuration.md 中的完整配置示例一个可用的最小配置如下{ name: my-agent, main: src/index.ts, compatibility_date: 2025-01-28, compatibility_flags: [nodejs_compat], durable_objects: { bindings: [ { name: MyAgent, class_name: MyAgent } ] }, migrations: [ { tag: v1, new_sqlite_classes: [MyAgent] } ] }配置要点在 SKILL.md 的 Wrangler Configuration 一节有明确警示nodejs_compat必开Agent 运行时依赖 Node 兼容标志每个 Agent 类都需要一对配置一个 DO bindingname与class_name对应 一条new_sqlite_classesmigration 记录两者缺一不可否则会出现 Namespace not found 类错误永远不要修改旧的 migration新增 Agent 类时追加新 tag如v2而不是改v1tsconfig 中不要开启experimentalDecorators它会破坏callable装饰器。完成配置后运行npx wrangler types生成类型化的env.d.ts详见 configuration.md。状态管理SQLite 持久化 自动广播Agents SDK 的状态模型非常简洁状态持久化到 SQLite并在每次变更时自动广播给所有已连接的客户端。你不需要手动处理读写冲突、持久化或推送框架替你完成了这三件事。定义类型化状态通过泛型AgentEnv, State声明状态类型并提供一个initialState作为该 Agent 实例的初始数据type State { count: number; items: string[]; }; export class MyAgent extends AgentEnv, State { initialState: State { count: 0, items: [] }; }类型化的好处是this.state的每次读取、setState的每次写入都会被 TS 静态检查杜绝把错误字段写入持久化层的低级错误。读取与更新// 读取从 SQLite 懒加载 const count this.state.count; // 写入同步、持久化、广播 this.setState({ count: this.state.count 1 });两条关键语义需要理解读取是懒加载的this.state在首次访问时才从 SQLite 载入而不是在 Agent 构造时全量加载这保证了冷启动hibernation 唤醒时的效率写入是同步且原子的setState完成“持久化 广播”后才返回你在写入之后立刻读取this.state一定能拿到新值。校验钩子validateStateChangevalidateStateChange(nextState, source)是一个**同步、门控gating**的钩子它在状态持久化之前执行通过抛异常拒绝非法更新。validateStateChange(nextState: State, source: Connection | server) { if (nextState.count 0) { throw new Error(Count cannot be negative); } }source参数标识状态变更的来源是某个 WebSocketConnection发来的还是服务端内部server触发的。你可以据此实现差异化策略例如只允许服务端把count置 0、拒绝客户端直接清零等。抛出异常后本次状态更新被整体拒绝不会写入 SQLite。一次 setState 的完整执行顺序从 state-scheduling.md 可以提取出严格的执行流水线validateStateChange(nextState, source)——同步、门控可抛异常拒绝写入状态持久化到 SQLite状态广播给所有已连接的客户端onStateUpdate(nextState, source)——异步通过ctx.waitUntil执行非门控不阻塞主流程。这意味着校验必须放在同步阶段抛异常才有意义而订阅方通知、日志、联动逻辑应放在异步的onStateUpdate里避免阻塞写入路径。SDK 还通过diagnostics_channel发布agents:state事件可用于观测每次状态变更见 observability.md 中的通道清单。客户端实时同步React状态广播在客户端由useAgent钩子承接。来自 state-scheduling.md 的完整示例import { useAgent } from agents/react; function App() { const [state, setLocalState] useStateState({ count: 0 }); const agent useAgentState({ agent: MyAgent, name: instance-1, onStateUpdate: (newState) setLocalState(newState) }); return button onClick{() agent.setState({ count: state.count 1 })} Count: {state.count} /button; }数据流是双向的服务端 → 客户端任何setState广播后onStateUpdate回调把最新状态灌入本地 React stateUI 自动刷新客户端 → 服务端agent.setState(...)通过 WebSocket 发往 Agent走完上文的四步执行流水线。useAgent还支持onIdentity回调、query鉴权参数、类型化的stubRPC 等能力详见 client-sdk.md非 React 环境可用AgentClientagents/client以事件监听方式接收stateUpdate。SQL API直连 SQLite 做自定义查询当setState的整块状态模型无法满足复杂查询时SDK 暴露了this.sql标签模板允许直接对底层 SQLite 执行 SQL。来自 state-scheduling.md 的完整示例// 建表 this.sql CREATE TABLE IF NOT EXISTS items ( id TEXT PRIMARY KEY, name TEXT, created_at INTEGER DEFAULT (unixepoch()) ) ; // 插入参数化防注入 this.sqlINSERT INTO items (id, name) VALUES (${id}, ${name}); // 带类型的查询 const items this.sql{ id: string; name: string } SELECT * FROM items WHERE name LIKE ${%${search}%} ;使用要点必须使用${}参数占位标签模板会自动做参数绑定杜绝 SQL 注入查询结果可声明泛型this.sqlRowType让结果集具备类型提示它与setState共享同一个 SQLite 存储因此你可以把聚合统计、全文检索等不适合整体状态模型的查询放到这里内置的 FIFO 队列this.queue同样基于 SQLite 持久化见 queue-retries.md二者可以配合使用。调度四种任务模式调度 API 覆盖了从“几秒后跑一次”到“每个工作日固定时刻”的全部需求。四种模式一览模式语法适用场景延迟Delaythis.schedule(60, ...)60 秒后执行一次定点Datethis.schedule(new Date(...), ...)指定时间点执行一次Cronthis.schedule(0 8 * * *, ...)周期性重复执行间隔Intervalthis.scheduleEvery(30, ...)固定间隔循环执行每 30 秒四种模式的完整示例// 延迟秒 await this.schedule(60, checkStatus, { id: abc123 }); // 指定日期时间 await this.schedule(new Date(2025-12-25T00:00:00Z), sendGreeting, { to: user }); // Cron工作日早上 9 点 await this.schedule(0 9 * * 1-5, weekdayReport, {}); // 固定间隔每 30 秒轮询一次自带防重叠 await this.scheduleEvery(30, pollUpdates); await this.scheduleEvery(300, syncData, { source: api });签名统一为schedule(when, callback, payload, options)when可以是秒数、Date对象或 Cron 表达式callback是 Agent 类上的方法名字符串payload是传给该方法的参数对象。scheduleEvery内置防重叠机制若上一个任务尚未完成不会叠加触发新一轮避免轮询类任务堆积。定义任务处理器处理器方法接收payload与schedule上下文两个参数async sendGreeting(payload: { to: string }, schedule: Schedule) { console.log(Sending greeting to ${payload.to}); // Cron 任务执行后自动重新排程 // 一次性任务delay/date执行后自动删除 }这里隐含了关键的生命周期语义Cron 任务是“自续”的执行完自动排下一次而一次性任务执行完即被删除——你不需要手动维护下一次触发时间。管理已排程任务const schedules this.getSchedules(); // 全部排程 const crons this.getSchedules({ type: cron }); // 仅 Cron 类型 await this.cancelSchedule(schedule.id); // 取消指定排程getSchedules({ type: cron })支持按类型过滤cancelSchedule接收schedule.id来自getSchedules的返回项。调度触发同样会发布agents:schedule可观测事件见 observability.md。为调度任务配置重试调度任务支持重试选项与 queue-retries.md 中this.retry()的重试机制共享同一套语义await this.schedule(60, task, payload, { retry: { maxAttempts: 3 } }); await this.scheduleEvery(30, poll, undefined, { retry: { maxAttempts: 2 } });注意一个关键限制源自 queue-retries.md 的 Important 一节调度/队列上的重试不支持shouldRetry自定义判定函数——因为回调不可序列化只有this.retry()方法支持shouldRetry。此外重试默认参数为 3 次尝试、100ms 基础延迟、3000ms 最大延迟指数退避 全抖动。生命周期回调状态变更之外的完整钩子state-scheduling.md 最后一节给出了完整的生命周期回调集合它们与状态系统共同构成 Agent 的运行时骨架export class MyAgent extends AgentEnv, State { async onStart() { // Agent 启动或从休眠hibernation中唤醒时触发 } onConnect(conn: Connection, ctx: ConnectionContext) { // WebSocket 客户端连接 } onMessage(conn: Connection, message: WSMessage) { // WebSocket 非 RPC 消息 } onStateUpdate(state: State, source: Connection | server) { // 状态变更异步、非阻塞对应上文执行顺序第 4 步 } onError(error: unknown) { // 错误处理重新 throw 以向上传播 throw error; } }各回调与状态/调度系统的关系onStartAgent 每次被唤醒包括冷启动与调度任务触发都会执行适合做初始化、续跑未完成任务onStateUpdate非门控的异步通知与validateStateChange的同步门控形成互补onError若不重新抛出错误会被吞掉重新throw才能让错误冒泡到调用方或可观测系统。结合 autoskills 仓库本技能在 Agent 工程中的定位上述全部内容并非孤立笔记而是 autoskills 仓库agents-sdk技能包SKILL.md中“状态与调度”这一参考文档的完整展开。在技能体系里它与其他参考文档共同覆盖一个有状态 Agent 的完整生命周期routing.md/agents/{kebab-class-name}/{instance-name}路由与routeAgentRequestcallable.mdcallable()RPC让客户端通过 WebSocket 调用 Agent 方法这也是setState最常见的服务端触发入口之一configuration.mdwrangler.jsonc、DO 绑定、migration、Vite 插件与 tsconfigqueue-retries.md与调度共享重试语义的内置 FIFO 队列observability.mdagents:state、agents:schedule等诊断通道用于观测状态变更与调度触发durable-execution.mdrunFiber/stash让长任务在 DO 被驱逐后仍能恢复——适合与scheduleEvery组合实现健壮的周期任务。其中“Persistent state — SQLite-backed, auto-synced to clients viasetState”与“Scheduling — One-time, recurring (scheduleEvery), and cron tasks”正是 SKILL.md 能力清单中明确定义的两项核心能力本文覆盖的正是这两条能力的 API 全貌。实战建议与注意事项把上述 API 组合成生产级 Agent 时注意以下几点校验先行所有外部输入WebSocket 客户端、RPC 参数导致的setState都应被validateStateChange校验它是最后一道防线合理选择调度模式固定间隔轮询用scheduleEvery自带防重叠跨天、跨周的业务节奏用 Cron一次性提醒用 Delay/Date区分重试边界this.retry()支持shouldRetry自定义策略而 schedule/queue 上的retry只有maxAttempts等序列化参数可用SQL 与状态配合高频小字段用setState同步大数据量、复杂查询走this.sql两者共享同一 SQLite 实例用观测通道兜底生产环境通过 Tail Worker 订阅diagnosticsChannelEvents把agents:state、agents:schedule事件转发到观测平台便于排查“状态为何变更、任务为何触发”。至此你已掌握 Cloudflare Agents SDK 状态与调度的完整闭环从wrangler.jsonc的 SQLite/DO 配置到类型化状态的读写与校验再到四种调度模式、任务重试与生命周期回调。这套能力足以支撑实时协作应用、定时数据同步、周期性巡检等绝大多数有状态 Agent 场景。赞分享【免费下载链接】autoskillsOne command. Your entire AI skill stack. Installed.项目地址https://gitcode.com/gh_mirrors/au/autoskills点击查看免费下载相关推荐Cloudflare Agents SDK 队列系统Queue完全指南基于 SQLite 的持久化异步任务调度Cloudflare Agents SDK 队列系统Queue完全指南基于 SQLite 的持久化异步任务调度 本指南系统讲解 Cloudflare AgAI AgentAgent 框架后端云原生MCP 服务实时通信Cloudflare Agents 状态管理实战指南持久化、双向同步与类型安全Cloudflare Agents 状态管理实战指南持久化、双向同步与类型安全 Agent 内置的状态管理State Management是构建实时协作应AI AgentAgent 框架后端云原生MCP 服务实时通信用 Cloudflare Agents 构建 Chat SDK 持久化状态agents/chat-sdk 完整接入指南用 Cloudflare Agents 构建 Chat SDK 持久化状态 agents/chat sdk 完整接入指南 导读 本指南聚焦 CloudflarAI AgentAgent 框架后端云原生MCP 服务实时通信上一篇PyOD 异常检测库实战指南从安装、统一 API 到算法选型与工程加速的完整解析下一篇Workerd 运行时 API 实战指南从 Worker 入口、Web 平台 API 到 CLI 与 Wrangler 集成创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考