agents

环境要求

• 已安装 Node.js 与 npm（需执行 npm 命令）
• 一个 Cloudflare 账号（Agent 运行在 Durable Objects 上）
• 已有项目需是 TypeScript 项目（README 示例为 TypeScript）
• 能访问 npm 仓库与 Cloudflare 官方文档站点

安装与启动步骤

1. 1用模板新建项目

   README 提供的官方推荐方式，一键生成 agents-starter 模板工程；执行后按命令行提示填写项目名等信息。

   npm create cloudflare@latest -- --template cloudflare/agents-starter

   复制

2. 2在现有项目装依赖

   如果你已有 Cloudflare Workers 项目，不需要模板，直接在该项目目录安装 agents 包即可。

   npm install agents

   复制

3. 3编写带状态的 Agent

   在 server.ts 中继承 Agent 类并定义可调用方法，用 setState 修改状态、this.state 读取状态，@callable() 暴露给前端。

   // server.ts
   import { Agent, routeAgentRequest, callable } from "agents";
   
   export type CounterState = { count: number };
   
   export class CounterAgent extends Agent<Env, CounterState> {
     initialState = { count: 0 };
   
     @callable()
     increment() {
       this.setState({ count: this.state.count + 1 });
       return this.state.count;
     }
   
     @callable()
     decrement() {
       this.setState({ count: this.state.count - 1 });
       return this.state.count;
     }
   }

   复制

4. 4查阅官方文档

   README 只给出入口示例，完整 API、路由与部署细节需按 README 指引到官方文档站查看，不要凭猜测写配置。

如何确认成功

模板创建或 npm install 无报错，项目中出现可编辑的 server.ts 且能看到 agents 依赖即成功。

常见问题

注意事项

• 本文档仅依据 README 节选整理，README 未出现的端口、路径、部署命令一律未填写，请以官方文档为准。
• README 的 Quick Example 代码在 fetch 处理函数处被截断，实际使用时需按官方文档补全 export default 部分。
• Agent 运行依赖 Cloudflare 平台能力（Durable Objects、Workflows 等），本地使用前建议先确认账号与项目环境。