跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

快速入门

最后更新 查看 MarkdownAgent 设置

构建能够持久化、思考并行动的 AI Agent。Agent 在 Cloudflare 全球网络上运行，在请求间维护状态，并通过 WebSocket 与客户端实时连接。

你将构建的内容： 一个将状态持久化并实时同步到 React 前端的计数器 Agent。

耗时： 约 10 分钟

创建新项目

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

然后安装依赖并启动开发服务器：

cd agents-starter
npm install
npm run dev

这将创建包含以下内容的项目：

  • src/server.ts — Agent 代码
  • src/client.tsx — React 前端
  • wrangler.jsonc — Cloudflare 配置
  • tsconfig.json — 继承 agents/tsconfig，用于正确的装饰器和模块设置
  • vite.config.ts — 包含 agents/vite 插件以支持装饰器

入门模板包含两个重要的 SDK 集成。若手动设置项目，请同时添加：

tsconfig.json — 继承 agents/tsconfig，其中设置 target: "ES2021" 及其他推荐选项：

{
	"extends": "agents/tsconfig"
}

vite.config.ts — 包含 agents() 插件，用于处理 TC39 装饰器转换（Vite 8 中 @callable() 所需）：

import { cloudflare } from "@cloudflare/vite-plugin";
import react from "@vitejs/plugin-react";
import agents from "agents/vite";
import { defineConfig } from "vite";

export default defineConfig({
	plugins: [agents(), react(), cloudflare()],
});

打开 http://localhost:5173 ↗ 查看 Agent 运行效果。

你的第一个 Agent

从零构建一个简单的计数器 Agent。替换 src/server.ts：

import { Agent, routeAgentRequest, callable } from "agents";

// Define the state shape

// Create the agent
export class CounterAgent extends Agent {
	// Initial state for new instances
	initialState = { count: 0 };

	// Methods marked with @callable can be called from the client
	@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;
	}

	@callable()
	reset() {
		this.setState({ count: 0 });
	}
}

// Route requests to agents
export default {
	async fetch(request, env, ctx) {
		return (
			(await routeAgentRequest(request, env)) ??
			new Response("Not found", { status: 404 })
		);
	},
};
src/server.tsts
import { Agent, routeAgentRequest, callable } from "agents";

// Define the state shape
export type CounterState = {
	count: number;
};

// Create the agent
export class CounterAgent extends Agent<Env, CounterState> {
	// Initial state for new instances
	initialState: CounterState = { count: 0 };

	// Methods marked with @callable can be called from the client
	@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;
	}

	@callable()
	reset() {
		this.setState({ count: 0 });
	}
}

// Route requests to agents
export default {
	async fetch(request: Request, env: Env, ctx: ExecutionContext) {
		return (
			(await routeAgentRequest(request, env)) ??
			new Response("Not found", { status: 404 })
		);
	},
} satisfies ExportedHandler<Env>;

更新 wrangler.jsonc 以注册 Agent：

{
	"name": "my-agent",
	"main": "src/server.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"compatibility_flags": ["nodejs_compat"],
	"durable_objects": {
		"bindings": [
			{
				"name": "CounterAgent",
				"class_name": "CounterAgent",
			},
		],
	},
	"migrations": [
		{
			"tag": "v1",
			"new_sqlite_classes": ["CounterAgent"],
		},
	],
}
name = "my-agent"
main = "src/server.ts"
# Set this to today's date
compatibility_date = "2026-08-17"
compatibility_flags = [ "nodejs_compat" ]

[[durable_objects.bindings]]
name = "CounterAgent"
class_name = "CounterAgent"

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "CounterAgent" ]

要点：

  • 绑定中的 name 成为 env 上的属性（例如 env.CounterAgent）
  • class_name 必须与导出的类名完全一致
  • new_sqlite_classes 启用 SQLite 存储以实现状态持久化
  • agents 包需要 nodejs_compat 标志

从 React 连接

替换 src/client.tsx：

src/client.tsxtsx
import "./styles.css";
import { createRoot } from "react-dom/client";
import { useState } from "react";
import { useAgent } from "agents/react";
import type { CounterAgent, CounterState } from "./server";

export default function App() {
	const [count, setCount] = useState(0);

	// Connect to the Counter agent
	const agent = useAgent<CounterAgent, CounterState>({
		agent: "CounterAgent",
		onStateUpdate: (state) => setCount(state.count),
	});

	return (
		<div style={{ padding: "2rem", fontFamily: "system-ui" }}>
			<h1>Counter Agent</h1>
			<p style={{ fontSize: "3rem" }}>{count}</p>
			<div style={{ display: "flex", gap: "1rem" }}>
				<button onClick={() => agent.stub.decrement()}>-</button>
				<button onClick={() => agent.stub.reset()}>Reset</button>
				<button onClick={() => agent.stub.increment()}>+</button>
			</div>
		</div>
	);
}

const root = createRoot(document.getElementById("root")!);
root.render(<App />);

要点：

  • useAgent 通过 WebSocket 连接 Agent
  • Agent 状态变更时触发 onStateUpdate
  • agent.stub.methodName() 调用 Agent 上用 @callable() 标记的方法

工作原理

当你点击按钮时：

  1. 客户端 通过 WebSocket 调用 agent.stub.increment()
  2. Agent 运行 increment()，通过 setState() 更新状态
  3. 状态 自动持久化到 SQLite
  4. 广播 发送给所有已连接的客户端
  5. React 通过 onStateUpdate 更新
flowchart LR
    A["Browser<br/>(React)"] <-->|WebSocket| B["Agent<br/>(Counter)"]
    B --> C["SQLite<br/>(State)"]

核心概念

概念 含义
Agent 实例 每个唯一名称对应一个独立 Agent。CounterAgent:user-123 与 CounterAgent:user-456 相互独立
持久化状态 状态在重启、部署和休眠后仍然保留，存储在 SQLite 中
实时同步 连接到同一 Agent 的所有客户端会即时收到状态更新
休眠 无客户端连接时，Agent 进入休眠（无费用），下次请求时唤醒

从原生 JavaScript 连接

若未使用 React：

import { AgentClient } from "agents/client";

const agent = new AgentClient({
	agent: "CounterAgent",
	name: "my-counter", // optional, defaults to "default"
	onStateUpdate: (state) => {
		console.log("New count:", state.count);
	},
});

// Call methods
await agent.call("increment");
await agent.call("reset");
import { AgentClient } from "agents/client";

const agent = new AgentClient({
	agent: "CounterAgent",
	name: "my-counter", // optional, defaults to "default"
	onStateUpdate: (state) => {
		console.log("New count:", state.count);
	},
});

// Call methods
await agent.call("increment");
await agent.call("reset");

部署到 Cloudflare

npm run deploy

你的 Agent 现已在 Cloudflare 全球网络上线，靠近用户运行。

常见集成模式

带身份验证的 Agent

在路由到 Agent 之前检查身份验证：

export default {
	async fetch(request, env) {
		// Check auth for agent routes
		if (request.url.includes("/agents/")) {
			const authResult = await checkAuth(request, env);
			if (!authResult.valid) {
				return new Response("Unauthorized", { status: 401 });
			}
		}

		const agentResponse = await routeAgentRequest(request, env);
		if (agentResponse) return agentResponse;

		// ... rest of routing
	},
};
export default {
	async fetch(request: Request, env: Env) {
		// Check auth for agent routes
		if (request.url.includes("/agents/")) {
			const authResult = await checkAuth(request, env);
			if (!authResult.valid) {
				return new Response("Unauthorized", { status: 401 });
			}
		}

		const agentResponse = await routeAgentRequest(request, env);
		if (agentResponse) return agentResponse;

		// ... rest of routing
	},
} satisfies ExportedHandler<Env>;

自定义 Agent 路径前缀

默认情况下，Agent 路由为 /agents/{agent-name}/{instance-name}。你可以自定义：

import { routeAgentRequest } from "agents";

const agentResponse = await routeAgentRequest(request, env, {
	prefix: "/api/agents", // Now routes at /api/agents/{agent-name}/{instance-name}
});
import { routeAgentRequest } from "agents";

const agentResponse = await routeAgentRequest(request, env, {
	prefix: "/api/agents", // Now routes at /api/agents/{agent-name}/{instance-name}
});

有关 CORS、自定义实例命名和 location hint 等更多选项，请参阅路由。

从服务端代码访问 Agent

你可以直接从 Worker 代码与 Agent 交互：

import { getAgentByName } from "agents";

export default {
	async fetch(request, env) {
		if (request.url.endsWith("/api/increment")) {
			// Get a specific agent instance
			const counter = await getAgentByName(env.CounterAgent, "shared-counter");
			const newCount = await counter.increment();
			return Response.json({ count: newCount });
		}
		// ...
	},
};
import { getAgentByName } from "agents";

export default {
	async fetch(request: Request, env: Env) {
		if (request.url.endsWith("/api/increment")) {
			// Get a specific agent instance
			const counter = await getAgentByName(env.CounterAgent, "shared-counter");
			const newCount = await counter.increment();
			return Response.json({ count: newCount });
		}
		// ...
	},
} satisfies ExportedHandler<Env>;

添加多个 Agent

通过扩展配置添加更多 Agent：

// src/agents/chat.ts
export class Chat extends Agent {
	// ...
}

// src/agents/scheduler.ts
export class Scheduler extends Agent {
	// ...
}
// src/agents/chat.ts
export class Chat extends Agent {
	// ...
}

// src/agents/scheduler.ts
export class Scheduler extends Agent {
	// ...
}

更新 Wrangler 配置文件：

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "durable_objects": {
    "bindings": [
      {
        "name": "CounterAgent",
        "class_name": "CounterAgent"
      },
      {
        "name": "Chat",
        "class_name": "Chat"
      },
      {
        "name": "Scheduler",
        "class_name": "Scheduler"
      }
    ]
  },
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": [
        "CounterAgent",
        "Chat",
        "Scheduler"
      ]
    }
  ]
}
[[durable_objects.bindings]]
name = "CounterAgent"
class_name = "CounterAgent"

[[durable_objects.bindings]]
name = "Chat"
class_name = "Chat"

[[durable_objects.bindings]]
name = "Scheduler"
class_name = "Scheduler"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["CounterAgent", "Chat", "Scheduler"]

从入口点导出所有 Agent：

export { CounterAgent } from "./agents/counter";
export { Chat } from "./agents/chat";
export { Scheduler } from "./agents/scheduler";
export { CounterAgent } from "./agents/counter";
export { Chat } from "./agents/chat";
export { Scheduler } from "./agents/scheduler";

故障排除

找不到 Agent，或 404 错误

  1. 检查导出 — Agent 类必须从主入口点导出。
  2. 检查绑定 — Wrangler 配置文件中的 class_name 必须与导出的类名完全一致。
  3. 检查路由 — 默认路由为 /agents/{'{agent-name}'}/{'{instance-name}'}。客户端中的 Agent 名称需与类名匹配（不区分大小写）。

No such Durable Object class 错误

在 Wrangler 配置文件中添加 migration：

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": [
        "YourAgentClass"
      ]
    }
  ]
}
[[migrations]]
tag = "v1"
new_sqlite_classes = ["YourAgentClass"]

WebSocket 连接失败

确保路由原样返回响应：

// Correct - return the response directly
const agentResponse = await routeAgentRequest(request, env);
if (agentResponse) return agentResponse;

// Wrong - this breaks WebSocket connections
if (agentResponse) return new Response(agentResponse.body);
// Correct - return the response directly
const agentResponse = await routeAgentRequest(request, env);
if (agentResponse) return agentResponse;

// Wrong - this breaks WebSocket connections
if (agentResponse) return new Response(agentResponse.body);

状态未持久化

请检查：

  1. 是否调用 this.setState()，而非直接修改 this.state。
  2. Agent 类是否在 migrations 的 new_sqlite_classes 中。
  3. 是否连接到同一 Agent 实例名称。
  4. 客户端是否已接入 onStateUpdate 回调。
  5. WebSocket 连接是否已建立（在浏览器开发者工具中检查）。

"Method X is not callable" 错误

确保方法已用 @callable() 装饰：

import { Agent, callable } from "agents";

export class MyAgent extends Agent {
	@callable()
	increment() {
		// ...
	}
}
import { Agent, callable } from "agents";

export class MyAgent extends Agent {
	@callable()
	increment() {
		// ...
	}
}

agent.stub 类型错误

添加 Agent 和 state 类型参数：

import { useAgent } from "agents/react";

// Pass the agent and state types to useAgent
const agent = useAgent({
	agent: "CounterAgent",
	onStateUpdate: (state) => setCount(state.count),
});

// Now agent.stub is fully typed
agent.stub.increment();
import { useAgent } from "agents/react";
import type { CounterAgent, CounterState } from "./server";

// Pass the agent and state types to useAgent
const agent = useAgent<CounterAgent, CounterState>({
	agent: "CounterAgent",
	onStateUpdate: (state) => setCount(state.count),
});

// Now agent.stub is fully typed
agent.stub.increment();

使用 @callable() 时出现 SyntaxError: Invalid or unexpected token

若开发服务器因此失败，请在 tsconfig.json 中设置 "target": "ES2021"。这可确保 Vite 的 esbuild 转译器将 TC39 装饰器降级，而非作为原生语法保留。

{
	"compilerOptions": {
		"target": "ES2021"
	}
}

后续步骤

现在你已有可运行的 Agent，可探索以下主题：

常见后续步骤

学习目标 参考文档
添加 AI/LLM 能力 使用 AI 模型
通过 MCP 暴露工具 MCP 服务器
运行后台任务 调度任务
处理邮件 Email 路由
使用 Cloudflare Workflows 运行 Workflows

进一步探索

状态管理

深入了解 setState()、initialState 和 onStateChanged()。

这篇文档对您有帮助吗？