# Cloudflare 代理 SDK **状态**：生产就绪 ✅ **最后更新**：2025-11-23 **依赖项**：cloudflare-worker-base（推荐）**最新版本**：agents@0.2.23（2025 年 11 月 13 日）、@modelcontextprotocol/sdk@latest **生产测试**：Cloudflare 自己的 MCP 服务器() **最近更新（2025）**： * **2025 年 9 月**：AI SDK v5 兼容性，自动消息迁移 * **2025 年 4 月**：MCP 支持（MCPAgent 类），从代理“导入 { context }” * **2025 年 3 月**：包重命名（agents-sdk → 代理） ** ** ## 什么是 Cloudflare 代理？ Cloudflare Agents SDK 支持构建在 Cloudflare Workers + Durable Objects 上运行的 AI 驱动的自主代理。代理商可以： * **通过 WebSocket 和服务器发送的事件进行实时通信** * **使用内置 SQLite 数据库保留状态**（每个代理最多 1GB） * **使用延迟、特定日期或 cron 表达式来安排任务** * **通过触发异步 Cloudflare 工作流程来运行工作流程** * **使用浏览器渲染 API + Puppeteer 浏览网页** * **使用 Vectorize 矢量数据库 + Workers AI 嵌入实现 RAG** * **构建 MCP 服务器** 实施模型上下文协议 * **支持人机交互**模式进行审核和批准 * **在全球范围内扩展到数百万**独立代理实例每个代理实例都是一个**全球唯一的、有状态的微服务器**，可以运行几秒、几分钟或几小时。 ** ** ## 您需要代理 SDK 吗？ **停止**：在使用 Agents SDK 之前，问问自己是否真的需要它。 ### 在以下情况下使用 JUST Vercel AI SDK（更简单）： * ✅ 构建一个基本的聊天界面 * ✅ 服务器发送事件 (SSE) 流就足够了（单向：服务器 → 客户端） * ✅ 不需要持久的代理状态（或者您使用 D1/KV 单独管理它） * ✅ 单用户、单对话场景 * ✅ 只需人工智能响应，无需复杂的工作流程或调度 **这涵盖了 80% 的聊天应用程序。** 对于这些情况，请直接在 Workers 上使用 [Vercel AI SDK]() - 它更简单，需要更少的基础设施，并自动处理流。 **示例**（无需 Agents SDK）： //worker.ts - 仅与 AI SDK 进行简单聊天从“ai”导入{streamText}；从'@ai-sdk/openai'导入{openai}；导出默认值{ 异步获取（请求：请求，环境：环境）{ const { messages } = 等待 request.json(); 常量结果=streamText({ 型号：openai('gpt-4o-mini'), 消息 }); 返回结果.toTextStreamResponse(); // 自动SSE流 } } // client.tsx - 使用内置钩子进行反应从 'ai/react' 导入 { useChat } ；函数聊天页面（）{ const { 消息、输入、handleSubmit } = useChat({ api: '/api/chat' }); // 完毕。无需代理 SDK。 } **结果**：100 行代码而不是 500 行。没有持久对象设置，没有 WebSocket 复杂性，没有迁移。 ** ** ### 当您需要时使用 Agents SDK： * ✅ **WebSocket 连接**（真正的双向实时通信） * ✅ **持久对象**（全局唯一的、有状态的代理实例） * ✅ **内置状态持久性**（每个代理的 SQLite 存储高达 1GB） * ✅ **多代理协调**（代理相互呼叫和通信） * ✅ **计划任务**（延迟、cron 表达式、重复作业） * ✅ **人机交互工作流程**（审批门、审核流程） * ✅ **长期运行的代理**（后台处理、自主工作流程） * ✅ **MCP 服务器** 具有有状态工具执行 **这大约是应用程序的 20%** \- 当您需要 Agents SDK 提供的基础架构时。 ** ** ### 关键理解：Agents SDK 是什么，不是什么 **代理 SDK IS**： * 🏗️ **基础设施层**，用于 WebSocket 连接、持久对象和状态管理 * 🔧 **用于构建有状态、自治代理的框架** * 📦 **使用生命周期方法围绕持久对象进行包装** **代理 SDK 不是**： * ❌ **AI推理提供商**（您自带：AI SDK、Workers AI、OpenAI等） * ❌ **流式响应处理程序**（使用AI SDK自动解析） * ❌ **LLM 整合**（这是一个单独的问题） **这样想**： * **代理 SDK** = 建筑物（WebSockets、状态、房间） * **AI SDK / Workers AI** = AI 大脑（推理、推理、响应）您可以一起使用它们（在大多数情况下推荐），或者直接使用 Workers AI（如果您愿意处理手动 SSE 解析）。 ** ** ### 决策流程图构建人工智能应用程序？ │ ├─ 需要WebSocket双向通信？ ────────┐ │（客户端在服务器流式传输时发送代理发起的消息） │ ├─ 需要持久对象有状态实例？ ──────────┤ │（具有持久记忆的全球唯一代理） │ ├─ 需要多智能体协调？ ──────────────────┤ │（客服人员给其他客服人员打电话/发消息） │ ├─ 需要计划任务或 cron 作业吗？ ──────────────┤ │（延迟执行、重复任务） │ ├─ 需要人机交互的工作流程吗？ ──────────────────┤ │（审批门、审核流程） │ └─ 如果以上皆为NO ──────────────────────────────→ 直接使用AI SDK （更简单的方法）如果以上任意一项为是 ────────────────────────────→ 使用 Agents SDK + AI SDK （更多基础设施，更多电力） ** ** ### 架构比较特色 |仅限 AI SDK |代理SDK+AI SDK ---|---|--- **设置复杂性** | 🟢 低（npm 安装，完成）| 🔴更高（耐用对象、迁移、绑定） **代码量** | 🟢 ~100 行 | 🟡 ~500 多行 **流媒体** | ✅ 自动（SSE）| ✅ 自动（AI SDK）或手动（Workers AI） **状态管理** | ⚠️ 手册 (D1/KV) | ✅ 内置（SQLite） **WebSocket** | ❌ 手动设置 | ✅ 内置 **反应挂钩** | ✅ useChat、useCompletion | ⚠️ 需要定制挂钩 **多代理** | ❌ 不支持 | ✅ 内置（routeAgentRequest） **日程安排** | ❌ 外部（队列/工作流）| ✅ 内置（this.schedule） **用例** |简单聊天，完成|复杂的有状态工作流程 ** ** ### 还不确定吗？ **从 AI SDK 开始。** 如果您发现需要 WebSocket 或持久对象，您可以稍后迁移到 Agents SDK。稍后添加基础设施比删除基础设施更容易。 **对于大多数开发者**：如果您正在构建聊天界面，并且对 WebSocket、多代理协调或计划任务没有特定要求，请直接使用 AI SDK。您将能够更快地交付并降低复杂性。 **仅当**您已确定对其基础设施功能的特定需求时，才继续使用 Agents SDK。 ** ** ## 快速入门（10 分钟） ### 1\.带模板的脚手架项目 npm create cloudflare@latest my-agent -- \ --template=cloudflare/agents-starter \ --ts\ --git \ --部署错误 **这会产生什么：** * 完整的Agent项目结构 * TypeScript配置 * wrangler.jsonc 与持久对象绑定 * 聊天代理实现示例 * 使用 useAgent 钩子响应客户端 ### 2\.或添加到现有工人 cd 我的现有工人 npm 安装代理 **然后创建一个Agent类：** // src/index.ts 从“代理”导入 { Agent, AgentNamespace }；导出类 MyAgent 扩展 Agent { 异步 onRequest(请求: 请求): Promise { return new Response("来自代理的您好！"); } } 导出默认MyAgent； ### 3\.配置持久对象绑定创建或更新 `wrangler.jsonc`： { "$schema": "node_modules/wrangler/config-schema.json", “姓名”：“我的代理人”， "main": "src/index.ts", “兼容性日期”：“2025-10-21”， “compatibility_flags”：[“nodejs_compat”]， “耐用对象”：{ “绑定”：[ { "name": "MyAgent", // 必须匹配类名 "class_name": "MyAgent" // 必须匹配导出的类 } ] }, “迁移”：[ { “标签”：“v1”， "new_sqlite_classes": ["MyAgent"] // 关键：启用 SQLite 存储 } ] } **关键配置规则：** * ✅ `name` 和 `class_name` **必须相同** * ✅ `new_sqlite_classes` **必须在第一次迁移中**（以后不能添加） * ✅ 代理类 **必须导出**（否则绑定会失败） * ✅ 迁移标签 **不能重复使用**（每个迁移都需要唯一的标签） ### 4\.部署 npx wrangler@最新部署您的代理现在正在运行：“https://my-agent..workers.dev” ** ** ## 架构概述：各部分如何组合在一起了解每种工具的用途可以防止混淆并帮助您选择正确的组合。 ### 堆栈 ┌──────────────────────────────────────────────────────────┐ │ 您的申请 │ │ │ │ ┌──────────────┐ ┌────────────────────┐ │ │ │ Agents SDK │ │ AI 推理 │ │ │ │ (下层) │ + │ (大脑层) │ │ │ │ │ │ │ │ │ │ • WebSockets │ │ 选择一个： │ │ │ │ • 耐用对象 │ │ • Vercel AI SDK ✅ │ │ │ │ • 状态 (SQL) │ │ • Workers AI ⚠️ │ │ │ │ • 调度 │ │ • OpenAI Direct │ │ │ │ • 多智能体 │ │ • 人类直接 │ │ │ └──────────────┘ └────────────────────┘ │ │ ↓ ↓ │ │ 管理连接生成响应 │ │ 状态和处理流 │ └──────────────────────────────────────────────────────────┘ ↓ Cloudflare Workers + 耐用对象 ### 每个工具提供什么 #### 1\.代理SDK（此技能） **目的**：有状态、实时代理的基础设施 **提供**： * ✅ WebSocket连接管理（双向实时） * ✅ 持久对象包装器（全局唯一的代理实例） * ✅ 内置状态持久性（SQLite 高达 1GB） * ✅ 生命周期方法（`onStart`、`onConnect`、`onMessage`、`onClose`） * ✅ 任务调度（带有 cron/delays 的 `this.schedule()`） * ✅ 多代理协调 (`routeAgentRequest()`) * ✅ 客户端库（`useAgent`、`AgentClient`、`agentFetch`） **不提供**： * ❌ AI 推理（无 LLM 调用） * ❌ 流式响应解析（自带） * ❌ 提供商集成（OpenAI、Anthropic 等） **将其视为**：建筑物和基础设施（房间、门、管道），但不是居民（AI）。 ** ** #### 2\. Vercel AI SDK（推荐用于 AI） **目的**：具有自动流式传输的人工智能推理 **提供**： * ✅ 自动流式响应处理（SSE 解析已为您完成） * ✅ 多提供商支持（OpenAI、Anthropic、Google 等） * ✅ React hooks (`useChat`, `useCompletion`, `useAssistant`) * ✅ 跨提供商的统一 API * ✅ 工具调用/函数调用 * ✅ 适用于 Cloudflare Workers ✅ **示例**：从“ai”导入{streamText}；从'@ai-sdk/openai'导入{openai}；常量结果=streamText({ 型号：openai('gpt-4o-mini'), 消息：[...] }); // 返回 SSE 流 - 无需手动解析返回结果.toTextStreamResponse(); **何时与 Agents SDK 一起使用**： * ✅ 大多数聊天应用程序 * ✅ 当你想要 React hooks 时 * ✅ 当您使用多个 AI 提供商时 * ✅ 当您想要干净、抽象的 AI 调用时 **与Agents SDK结合**：从“agents/ai-chat-agent”导入{ AIChatAgent }；从“ai”导入{streamText}；导出类 MyAgent 扩展 AIChatAgent { 异步 onChatMessage(onFinish) { // Agents SDK提供：WebSocket、state、this.messages // AI SDK提供：自动流式传输、提供者抽象返回流文本（{ 型号：openai('gpt-4o-mini'), messages: this.messages // 由 Agents SDK 管理 }).toTextStreamResponse(); } } ** ** #### 3\.工人人工智能（人工智能的替代品） **用途**：Cloudflare 的平台上 AI 推理 **提供**： * ✅ 具有成本效益的推理（包含在 Workers 订阅中） * ✅ 无需外部 API 密钥 * ✅ 模型：LLaMA 3、Qwen、Mistral、embeddings 等。 * ✅ 在 Cloudflare 网络上运行（低延迟） **不提供**： * ❌自动流式解析（返回原始SSE格式） * ❌ 反应钩子 * ❌ 多提供商抽象 **需要手动解析**： const 响应 = 等待 env.AI.run('@cf/meta/llama-3-8b-instruct', { 消息：[...]，流：真实 }); // 返回原始 SSE 格式 - 您必须解析 for等待（常量响应块）{ const text = new TextDecoder().decode(chunk); // Uint8Array → 字符串 if (text.startsWith('data: ')) { // 检查 SSE 格式 const data = JSON.parse(text.slice(6)); // 解析 JSON if (data.response) { // 提取.response字段 fullResponse += data.response; } } } **何时使用**： * ✅ 成本至关重要（嵌入、大批量） * ✅ 需要 Cloudflare 特定模型 * ✅ 愿意处理手动SSE解析 * ✅ 不允许外部依赖 **权衡**：省钱，花时间进行手动解析。 ** ** ### 推荐组合 #### 选项 A：Agents SDK + Vercel AI SDK（推荐 ⭐） **使用时**：您需要 WebSockets/状态并且想要干净的 AI 集成从“agents/ai-chat-agent”导入{ AIChatAgent }；从“ai”导入{streamText}；从“@ai-sdk/openai”导入{openai}；导出类 ChatAgent 扩展 AIChatAgent { 异步 onChatMessage(onFinish) { 返回流文本（{ 型号：openai('gpt-4o-mini'), messages: this.messages, // Agents SDK 管理历史记录完成时 }).toTextStreamResponse(); } } **优点**： * ✅ 最佳开发者体验 * ✅ 自动串流 * ✅ WebSockets + Agents SDK 的状态 * ✅ 干净、可维护的代码 **缺点**： * ⚠️ 需要外部 API 密钥 * ⚠️ AI 提供商的额外费用 ** ** #### 选项 B：Agents SDK + Workers AI **何时使用**：您需要 WebSockets/状态并且成本至关重要从“代理”导入{代理}；导出类 BudgetAgent 扩展 Agent { 异步 onMessage（连接，消息）{ const 响应 = 等待 this.env.AI.run('@cf/meta/llama-3-8b-instruct', { 消息：[...]，流：真实 }); // 需要手动 SSE 解析（请参阅上面的 Workers AI 部分） for等待（常量响应块）{ // ...手动解析... } } } **优点**： * ✅ 性价比高 * ✅ 无外部依赖 * ✅ WebSockets + Agents SDK 的状态 **缺点**： * ❌ 手动SSE解析复杂度 * ❌ 有限的型号选择 * ❌需要维护更多代码 ** ** #### 选项 C：仅 Vercel AI SDK（无代理） **使用时**：您不需要 WebSocket 或持久对象 //worker.ts - 简单的Workers路线导出默认值{ 异步获取（请求：请求，环境：环境）{ const { messages } = 等待 request.json(); 常量结果=streamText({ 型号：openai('gpt-4o-mini'), 消息 }); 返回结果.toTextStreamResponse(); } } // client.tsx - 内置 React hooks 从 'ai/react' 导入 { useChat } ；功能聊天（）{ const { 消息、输入、handleSubmit } = useChat({ api: '/api/chat' }); 返回 ; } **优点**： * ✅ 最简单的方法 * ✅ 最少的代码 * ✅ 快速实施 * ✅ 内置 React 钩子 **缺点**： * ❌ 无 WebSocket（仅限 SSE） * ❌ 无持久对象状态 * ❌ 无多智能体协调 **最适合**：80% 的聊天应用程序 ** ** ### 决策矩阵您的需求 |推荐堆栈 |复杂性 |成本 ---|---|---|--- 简单聊天，无状态|仅AI SDK | 🟢 低 | $$（人工智能提供商）聊天 + WebSockets + 状态 |代理SDK+AI SDK | 🟡 中等 | $$$（基础设施+人工智能）聊天 + WebSockets + 预算 |代理SDK + Workers AI | 🔴高| $（仅限下文）多代理工作流程 |代理SDK+AI SDK | 🔴高| $$$（基础设施+人工智能） MCP 服务器与工具 |代理SDK (McpAgent) | 🟡 中等 | $（仅限下文） ** ** ### 要点 **Agents SDK 是基础设施，而不是 AI。** 您可以将其与 AI 推理工具结合起来： * **为了获得最佳 DX**：Agents SDK + Vercel AI SDK ⭐ * **为了节省成本** ：Agents SDK + Workers AI（接受手动解析） * **为简单起见**：只需 AI SDK（如果您不需要 WebSockets/state）该技能的其余部分重点关注 Agents SDK（基础设施层）。有关 AI 推理模式，请参阅“ai-sdk-core”或“cloudflare-workers-ai”技能。 ** ** ## 配置（wrangler.jsonc） **关键所需配置**： { “耐用对象”：{ “绑定”：[{“名称”：“MyAgent”，“class_name”：“MyAgent”}] }, “迁移”：[ { "tag": "v1", "new_sqlite_classes": ["MyAgent"] } // 必须位于第一次迁移中 ] } **常见可选绑定**：`ai`、`vectorize`、`browser`、`workflows`、`d1_databases`、`r2_buckets` **关键迁移规则**： * ✅ `new_sqlite_classes` 必须位于标签“v1”中（无法将 SQLite 添加到现有部署的类中） * ✅ `name` 和 `class_name` 必须完全匹配 * ✅ 迁移是原子的（所有实例同时更新） * ✅ 每个标签必须是唯一的，不能编辑/删除以前的标签 **参见**： ** ** ## 核心代理模式 **代理类基础知识** \- 使用生命周期方法扩展 `Agent`： * `onStart()` \- 代理初始化 * `onRequest()` \- 处理 HTTP 请求 * `onConnect/onMessage/onClose()` \- WebSocket 处理 * `onStateUpdate()` \- 对状态变化做出反应 **关键属性**： * `this.env` \- 环境绑定（AI、DB 等） * `this.state` \- 当前代理状态（只读） * `this.setState()` \- 更新持久状态 * `this.sql` \- 内置 SQLite 数据库 * `this.name` \- 代理实例标识符 * `this.schedule()` \- 安排未来的任务 **参见**：官方代理 API 文档，位于 ** ** ## WebSockets 和实时通信代理支持 WebSocket 进行双向实时通信。当你需要时使用： * 客户端可以在服务器发送消息的同时发送消息 * 代理发起的消息（通知、更新） * 与国家的长期联系 **基本模式**：导出类 ChatAgent 扩展 Agent { 异步 onConnect(连接: Connection, ctx: ConnectionContext) { // 身份验证、添加参与者、发送欢迎信息 } 异步onMessage（连接：连接，消息：WSMessage）{ // 处理消息、更新状态、广播响应 } } **SSE 替代方案**：对于单向服务器 → 客户端流（更简单，基于 HTTP），请使用服务器发送事件而不是 WebSocket。 **参见**： ** ** ## 状态管理 **两种状态机制**： 1. **`this.setState(newState)`** \- JSON 可序列化状态（最大 1GB） * 自动持久化，同步到WebSocket客户端 * 用于：用户偏好、会话数据、小型数据集 2. **`this.sql`** \-内置SQLite数据库（最大1GB） * 标记模板文字可防止 SQL 注入 * 用于：关系数据、大型数据集、复杂查询 **国家规则**： * ✅ 仅 JSON 可序列化（对象、数组、基元、null） * ✅ 重启后仍然存在，立即一致 * ❌ 无函数或循环引用 * ❌ 1GB 总限制（状态 + SQL 组合） **SQL 模式**：等待this.sql`如果用户不存在则创建表（id INTEGER PRIMARY KEY，电子邮件文本）` wait this.sql`INSERT INTO users (email) VALUES (${userEmail})` // ← 准备好的语句 const users = wait this.sql`SELECT * FROM users WHERE email = ${email}` // ← 返回数组 **参见**： ** ** ## 安排任务代理可以使用“this.schedule()”安排任务在将来运行。 ### 延迟（秒）导出类 MyAgent 扩展 Agent { 异步 onRequest(请求: 请求): Promise { // 安排任务在 60 秒内运行 const { id } = wait this.schedule(60, "checkStatus", { requestId: "123" }); 返回 Response.json({ ScheduledTaskId: id }); } // 该方法将在 60 秒后被调用异步 checkStatus(数据: { requestId: string }) { console.log('检查请求状态：', data.requestId); // 执行检查、更新状态、发送通知等。 } } ### 具体日期导出类 MyAgent 扩展 Agent { 异步 ScheduleReminder(reminderDate: string) { const 日期 = 新日期(reminderDate); const { id } = 等待 this.schedule(日期, "sendReminder", { 消息：“预约时间到了！” }); 返回ID； } 异步 sendReminder(数据: { 消息: 字符串 }) { console.log('发送提醒：', data.message); // 发送电子邮件、推送通知等 } } ### Cron 表达式导出类 MyAgent 扩展 Agent { 异步 setupRecurringTasks() { // 每10分钟一次等待 this.schedule("*/10 * * * *", "checkUpdates", {}); // 每天早上 8 点 wait this.schedule("0 8 * * *", "dailyReport", {}); //每周一上午 9 点 wait this.schedule("0 9 * * 1", "weeklyReport", {}); // 每小时整点 wait this.schedule("0 * * * *", "hourlyCheck", {}); } 异步 checkUpdates(数据：任意) { console.log('正在检查更新...'); } 异步每日报告（数据：任意）{ console.log('正在生成每日报告...'); } 异步每周报告（数据：任意）{ console.log('正在生成每周报告...'); } 异步每小时检查（数据：任何）{ console.log('运行每小时检查...'); } } ### 管理计划任务导出类 MyAgent 扩展 Agent { 异步管理计划（）{ // 获取所有计划任务 const allTasks = this.getSchedules(); console.log('任务总数：', allTasks.length); // 根据ID获取具体任务 const taskId = "某个任务 ID"; const 任务 = 等待 this.getSchedule(taskId); 如果（任务）{ console.log('任务：', task.callback, 'at', new Date(task.time)); console.log('有效负载：', 任务.有效负载); console.log('类型：', 任务.type); //“预定”| “延迟”| “克罗恩” // 取消任务 const 取消=等待 this.cancelSchedule(taskId); console.log('已取消：', 已取消); } // 获取时间范围内的任务 const即将到来的任务 = this.getSchedules({ 时间范围：{ 开始：新日期（）， end: new Date(Date.now() + 24 * 60 * 60 * 1000) // 接下来的 24 小时 } }); console.log('即将到来的任务：',comingTasks.length); // 按类型过滤 const cronTasks = this.getSchedules({ 类型: "cron" }); const DelayedTasks = this.getSchedules({ type: "delayed" }); } } **调度约束：** * 每个任务映射到一个 SQL 数据库行（每个任务最多 2 MB） * 任务总数限制为：`(task_size * count) + other_state < 1GB` * Cron 任务继续运行，直到明确取消 * 回调方法必须存在于代理类上（如果缺少则抛出错误） **严重错误**：如果回调方法不存在： // ❌ 不好：方法不存在等待 this.schedule(60, "nonExistentMethod", {}); // ✅ 好：方法存在等待 this.schedule(60, "existingMethod", {}); 异步现有方法（数据：任何）{ // 实现 } ** ** ## 运行工作流程代理可以触发异步 [Cloudflare 工作流程]()。 ### 工作流绑定配置 `牧马人.jsonc`： { “工作流程”：[ { “名称”：“MY_WORKFLOW”， "class_name": "我的工作流程" } ] } 如果工作流位于不同的脚本中： { “工作流程”：[ { “名称”：“EMAIL_WORKFLOW”， "class_name": "电子邮件工作流程", "script_name": "email-workflows" // 不同的项目 } ] } ### 触发工作流程从“代理”导入{代理}；从“cloudflare:workers”导入{ WorkflowEntrypoint、WorkflowEvent、WorkflowStep }；接口环境{ MY_WORKFLOW：工作流程； MyAgent: AgentNamespace; } 导出类 MyAgent 扩展 Agent { 异步 onRequest(请求: 请求): Promise { const userId = new URL(request.url).searchParams.get('userId'); // 立即触发工作流程 const 实例 = 等待 this.env.MY_WORKFLOW.create({ id: `用户-${userId}`, 参数：{ userId，操作：“进程”} }); // 或者安排一个延迟的工作流程触发器等待 this.schedule(300, "runWorkflow", { userId }); 返回 Response.json({workflowId:instance.id }); } 异步 runWorkflow(数据: { userId: string }) { const 实例 = 等待 this.env.MY_WORKFLOW.create({ id: `延迟-${data.userId}`, 参数：数据 }); // 定期监控工作流状态 wait this.schedule("*/5 * * * *", "checkWorkflowStatus", { id: instance.id }); } 异步 checkWorkflowStatus(data: { id: string }) { // 检查工作流程状态（有关详细信息，请参阅工作流程文档） console.log('检查工作流程：', data.id); } } // 工作流程定义（可以位于相同或不同的文件/项目中）导出类 MyWorkflow 扩展 WorkflowEntrypoint { 异步运行（事件：WorkflowEvent <{ userId：string }>，步骤：WorkflowStep）{ // 工作流程实现 const result = wait step.do('处理数据', async () => { 返回{已处理：true}； }); 返回结果； } } ### 代理与工作流程特色 |代理|工作流程 ---|---|--- **目的** |交互式、面向用户 |后台处理 **持续时间** |秒到小时|分钟到小时 **状态** | SQLite 数据库 |基于步骤的检查点 **互动** | WebSockets、HTTP |无直接互动 **重试** |手册|每步自动 **用例** |聊天，实时UI | ETL、批处理 **最佳实践**：使用代理来**协调**多个工作流程。代理可以触发、监控和响应工作流程结果，同时保持用户交互。 ** ** ## 浏览网页代理可以使用浏览器渲染进行网页抓取和自动化： **绑定**：将 `"browser": { "binding": "BROWSER" }` 添加到 wrangler.jsonc **包**：`@cloudflare/puppeteer` **用例**：网页抓取、屏幕截图、代理工作流程中的自动浏览 **请参阅**：`cloudflare-browser-rendering` 技能以获取完整的 Puppeteer + Workers 集成指南。 ** ** ## 检索增强生成 (RAG) 代理可以使用 Vectorize（向量数据库）+ Workers AI（嵌入）来实现 RAG： **模式**：摄取文档 → 生成嵌入 → 存储在 Vectorize 中 → 查询 → 检索上下文 → 传递给 AI **绑定**： * `"ai": { "binding": "AI" }` \- 用于嵌入的 Workers AI * `"向量化": { "绑定": [{ "绑定": "VECTORIZE", "index_name": "我的向量" }] }` \- 向量搜索 **典型工作流程**： 1. 使用 Workers AI 生成嵌入 (`@cf/baai/bge-base-en-v1.5`) 2. 将向量更新插入到 Vectorize (`this.env.VECTORIZE.upsert(vectors)`) 3. 查询相似向量(`this.env.VECTORIZE.query(queryVector, { topK: 5 })`) 4. 在AI提示中使用检索到的上下文 **请参阅**：`cloudflare-vectorize` 技能以获取完整的 RAG 实施指南。 ** ** ## 使用人工智能模型代理可以使用以下方式调用 AI 模型： * **Vercel AI SDK**（推荐）：多提供商、自动流式传输、工具调用 * **Workers AI** ：Cloudflare 的平台推理（经济有效，手动解析） **架构说明**：Agents SDK 提供基础设施（WebSockets、状态、调度）。 AI 推理是一个单独的层 - 使用 AI SDK 作为“大脑”。 **看** ： * 完整的AI SDK集成模式的“ai-sdk-core”技能 * 用于Workers AI流解析的“cloudflare-workers-ai”技能 ** ** ## 呼叫代理 **两种主要模式**： 1. **`routeAgentRequest(request, env)`** \- 通过 URL 模式自动路由 `/agents/:agent/:name` * 示例： `/agents/my-agent/user-123` 路由到 MyAgent 实例“user-123” 2. **`getAgentByName(env.AgentBinding, instanceName)`** \- 自定义路由 * 返回用于调用方法或传递请求的代理存根 * 示例：`const agent = getAgentByName(env.MyAgent, 'user-${userId}')` **多代理通信**：导出类 AgentA 扩展 Agent { 异步 processData(数据：任意) { const agentB = getAgentByName(this.env.AgentB, 'processor-1'); 返回等待（等待agentB）.analyze（数据）； } } **关键安全性**：在创建/访问代理之前，始终在 Worker 中进行身份验证。代理应假设呼叫者已获得授权。 **参见**： ** ** ## 客户端 API **浏览器/React 集成**： * **`AgentClient`** (来自 `agents/client`) - 浏览器的 WebSocket 客户端 * **`agentFetch`**（来自`agents/client`） - 对代理的 HTTP 请求 * **`useAgent`** (来自 `agents/react`) - 用于 WebSocket 连接 + 状态同步的 React 钩子 * **`useAgentChat`** (来自 `agents/ai-react`) - 预构建的聊天 UI 钩子 **所有客户端库自动处理**：WebSocket 连接、状态同步、重新连接逻辑。 **参见**： ** ** ## 模型上下文协议（MCP）使用 Agents SDK 构建 MCP 服务器。 ### MCP 服务器设置 npm install @modelcontextprotocol/sdk 代理 ### 基本 MCP 服务器从“agents/mcp”导入{McpAgent}；从“@modelcontextprotocol/sdk/server/mcp.js”导入{McpServer}；从“zod”导入{z}；导出类 MyMCP 扩展 McpAgent { server = new McpServer({ 名称: "演示", 版本: "1.0.0" }); 异步初始化() { // 定义一个工具这个.服务器.工具（ “添加”， “将两个数字相加”， { a: z.number().describe("第一个数字"), b: z.number().describe("第二个数字") }, 异步 ({ a, b }) => ({ 内容：[{类型：“文本”，文本：字符串（a + b）}] }) ）； } } ### 有状态 MCP 服务器类型状态 = { 计数器：数字 }; 导出类 StatefulMCP 扩展 McpAgent { server = new McpServer({ 名称: "Counter", 版本: "1.0.0" }); 初始状态：状态= {计数器：0}；异步初始化() { // 资源 this.server.resource( “柜台”， “mcp://资源/计数器”，（uri）=>（{ 内容：[{ uri: uri.href, 文本: String(this.state.counter) }] }) ）； // 工具这个.服务器.工具（ “增量”， “增加计数器”， { 金额：z.number() }, 异步（{金额}）=> { this.setState({ ...这个状态，计数器：this.state.counter + 金额 }); 返回{ 内容：[{ 类型：“文本”， text: `计数器现在是 ${this.state.counter}` }] }; } ）； } } ### MCP 传输配置从'hono'导入{Hono}； const app = new Hono(); // 现代流式 HTTP 传输（推荐） app.mount('/mcp', MyMCP.serve('/mcp').fetch, { ReplaceRequest: false }); // 旧版 SSE 传输（已弃用） app.mount('/sse', MyMCP.serveSSE('/sse').fetch, { ReplaceRequest: false }); 导出默认应用程序； **交通比较：** * **/mcp** ：流式 HTTP（现代，推荐） * **/sse** ：服务器发送的事件（旧版，已弃用） ### MCP 与 OAuth 从 '@cloudflare/workers-oauth-provider' 导入 { OAuthProvider }；导出默认新 OAuthProvider({ apiHandlers: { '/sse': MyMCP.serveSSE('/sse'), '/mcp': MyMCP.serve('/mcp') }, // OAuth 配置 clientId: '您的客户 ID', clientSecret: '您的客户秘密', // ...其他 OAuth 设置 }); ### 测试 MCP 服务器 # 运行 MCP 检查器 npx @modelcontextprotocol/inspector@latest # 连接到：http://localhost:8788/mcp **Cloudflare 的 MCP 服务器**：有关生产示例，请参阅[参考]()。 ** ** ## 关键规则 ### 永远这样做 ✅ 1. **导出代理类** \- 必须导出才能绑定工作 2. **在 v1 迁移中包含 new_sqlite_classes** \- 以后无法添加 SQLite 3. **将绑定名称与类名称匹配** \- 防止“找不到绑定”错误 4. **在 Worker 中进行身份验证，而不是在 Agent 中** \- 安全最佳实践 5. **对 SQL 使用标记模板文字** \- 防止 SQL 注入 6. **处理 WebSocket 断开连接** \- 状态持续存在，连接不存在 7. **验证计划任务回调是否存在** \- 如果方法丢失，则抛出错误 8. **使用全局唯一实例名称** \- 相同名称=全局相同代理 9. **检查状态大小限制** \- 每个代理最大总计 1GB 10. **监控任务负载大小** \- 每个计划任务最大 2MB 11. **正确使用工作流绑定** \- 必须在 wrangler.jsonc 中配置 12. **插入前创建 Vectorize 索引** \- 元数据过滤所需 13. **关闭浏览器实例** \-防止资源泄漏 14. **使用 setState() 进行持久化** \- 不要只修改 this.state 15. **首先在本地测试迁移** \- 迁移是原子的，无法回滚 ### 永远不要这样做❌ 1. **不要将 SQLite 添加到现有部署的类** \- 必须在第一次迁移中 2. **不要逐步部署迁移** \- 仅原子 3. **不要跳过 Worker 中的身份验证** \- 始终在代理访问之前进行身份验证 4. **不要手动构造 SQL 字符串** \- 使用标记模板 5. **每个代理不要超过 1GB 状态** \- 硬限制 6. **不要安排不存在回调的任务** \- 运行时错误 7. **不要假设相同的名称 = 不同的代理** \- 全球唯一性 8. **不要将 SSE 用于 MCP** \- 已弃用，使用 /mcp 传输 9. **不要忘记浏览器绑定** \- 网页浏览所需 10. **不要直接修改this.state** \- 使用setState()代替 ** ** ## 已知问题预防此技能可防止 **16+** 记录的问题： ### 问题 1：迁移不是原子的 **错误**：“无法逐步部署迁移” **来源**： **原因**：迁移同时应用于所有实例 **预防**：独立于代码更改部署迁移，使用“npx wrangler versions deploy” ### 问题 2：缺少 new_sqlite_classes **错误**：“无法在现有类上启用 SQLite” **来源**： **为什么**：必须在第一次迁移中启用 SQLite **预防**：在标记“v1”迁移中包含 `new_sqlite_classes` ### 问题 3：代理类未导出 **错误**：“找不到绑定”或“无法访问未定义” **来源**： **为什么**：持久对象需要导出类 **预防**：`导出类 MyAgent 扩展代理`（使用导出关键字） ### 问题 4：绑定名称不匹配 **错误**：“未找到绑定‘X’” **来源**： **原因**：绑定名称必须与类名完全匹配 **预防**：确保 wrangler.jsonc 中的 `name` 和 `class_name` 相同 ### 问题 5：全球独特性未被理解 **错误**：代理实例出现意外行为 **来源**： **为什么**：相同的名称始终在全局返回相同的代理实例 **预防**：对实例名称使用唯一标识符（userId、sessionId） ### 问题 6：WebSocket 状态未持久 **错误**：断开连接后连接状态丢失**来源**： **为什么**：WebSocket 连接不会持久，但代理状态会保留 **预防**：通过 setState() 将重要数据存储在代理状态中，而不是连接状态中 ### 问题七：定时任务回调不存在 **错误**：“代理上不存在方法 X” **来源**： **为什么**：this.schedule() 调用未定义的方法 **预防**：确保调度之前存在回调方法 ### 问题 8：超出状态大小限制 **错误**：“超出最大数据库大小” **来源**： **原因**：代理状态 + 计划任务超过 1GB **预防**：监控状态大小，使用外部存储（D1、R2）存储大数据 ### 问题 9：计划任务太大 **错误**：“任务负载超过 2MB” **来源**： **原因**：每个任务映射到具有 2MB 限制的数据库行 **预防**：保持任务负载最小化，在代理状态/SQL 中存储大量数据 ### 问题 10：工作流绑定缺失 **错误**：“无法读取未定义的属性‘create’” **来源**： **原因**：未在 wrangler.jsonc 中配置工作流绑定 **预防**：在使用 this.env.WORKFLOW 之前添加工作流绑定 ### 问题 11：需要浏览器绑定 **错误**：“BROWSER 绑定未定义” **来源**： **为什么**：浏览器渲染需要显式绑定 **预防**：将 `"browser": { "binding": "BROWSER" }` 添加到 wrangler.jsonc ### 问题 12：未找到矢量化索引 **错误**：“索引不存在” **来源**： **为什么**：使用前必须创建 Vectorize 索引 **预防**：在部署代理之前运行 `wrangler vectorize create` ### 第 13 期：MCP 传输混乱 **错误**：“SSE 传输已弃用” **来源**： **原因**：SSE 传输是旧版，建议使用流式 HTTP **预防**：将 `/mcp` 端点与 `MyMCP.serve('/mcp')` 一起使用，而不是 `/sse` ### 问题 14：身份验证绕过 **错误**：安全漏洞 **来源**： **为什么**：在 Agent 而不是 Worker 中完成身份验证 **预防**：在调用 getAgentByName() 之前始终在 Worker 中进行身份验证 ### 问题 15：实例命名错误 **错误**：跨用户数据泄露 **来源**： **原因**：不良的实例命名允许访问错误的代理 **预防**：使用命名空间名称，如 `user-${userId}`，验证所有权 ###第16期：Workers AI Streaming需要手动解析 **错误**：“无法读取未定义的属性‘响应’或空 AI 响应 **来源**： **为什么**：Workers AI 以服务器发送事件 (SSE) 格式将流响应返回为 `Uint8Array`，而不是普通对象 **预防**：使用 `TextDecoder` \+ SSE 解析模式（请参阅“Workers AI（替代AI）”上面的部分） **问题** \- 尝试直接访问流块失败： const response = wait env.AI.run(model, {stream: true }); for等待（常量响应块）{ console.log(块.响应); // ❌ undefined - chunk 是 Uint8Array，而不是 object } **解决办法** \- 手动解析SSE格式： const response = wait env.AI.run(model, {stream: true }); for等待（常量响应块）{ const text = new TextDecoder().decode(chunk); // 步骤 1：Uint8Array → 字符串 if (text.startsWith('data: ')) { // 步骤 2：检查 SSE 格式 const jsonStr = text.slice(6).trim(); // 步骤 3：从“data: {...}”中提取 JSON if (jsonStr === '[完成]') 中断; // 第四步：处理终止 const 数据 = JSON.parse(jsonStr); // 步骤5：解析JSON if (data.response) { // 第 6 步：提取 .response 字段 fullResponse += data.response; } } } **更好的替代方案**：使用 Vercel AI SDK 自动处理此问题：从“ai”导入{streamText}；从'@ai-sdk/cloudflare'导入{createCloudflare}； const cloudflare = createCloudflare(); 常量结果=streamText({ 模型：cloudflare('@cf/meta/llama-3-8b-instruct', { 绑定: env.AI }), 消息 }); // 无需手动解析 ✅ **何时接受手动解析** : * 成本至关重要（Workers AI 更便宜） * 不允许外部依赖 * 愿意维护SSE解析代码 **何时使用 AI SDK** ： * 重视开发人员时间而不是计算成本 * 想要自动串流 * 需要多提供商支持 ** ** ## 依赖关系 ### 必填 * **cloudflare-worker-base** \- 基金会（Hono、Vite、Workers 设置） ### 可选（按功能） * **cloudflare-workers-ai** \- 用于 Workers AI 模型调用 * **cloudflare-vectorize** \- 对于带有 Vectorize 的 RAG * **cloudflare-d1** \- 用于代理状态之外的额外持久存储 * **cloudflare-r2** \- 用于文件存储 * **cloudflare-queues** \- 用于消息队列 ### NPM 包 * `agents` \- Agents SDK（必需） * `@modelcontextprotocol/sdk` \- 用于构建 MCP 服务器 * `@cloudflare/puppeteer` \- 用于网页浏览 * `ai` \- 用于模型调用的AI SDK * `@ai-sdk/openai` \- OpenAI 模型 * `@ai-sdk/anthropic` \- 人择模型 ** ** ## 官方文档 * **代理 SDK** ： * **API 参考**： * **持久对象**： * **工作流程**： * **矢量化** : * **浏览器渲染** : * **模型上下文协议** : * **Cloudflare MCP 服务器**： ** ** ## 捆绑资源 ### 模板（模板/） * `wrangler-agents-config.jsonc` \- 完整配置示例 * `basic-agent.ts` \- 最小 HTTP 代理 * `websocket-agent.ts` \- WebSocket 处理程序 * `state-sync-agent.ts` \- 状态管理模式 * `scheduled-agent.ts` \- 任务调度 * `workflow-agent.ts` \- 工作流程集成 * `browser-agent.ts` \- 网页浏览 * `rag-agent.ts` \- RAG 实现 * `chat-agent-streaming.ts` \- 流媒体聊天 * `calling-agents-worker.ts` \- 代理路由 * `react-useagent-client.tsx` \- React 客户端 * `mcp-server-basic.ts` \- MCP 服务器 * `hitl-agent.ts` \- 人机交互 ### 参考文献（参考文献/） * `agent-class-api.md` \- 完整的 Agent 类参考 * `client-api-reference.md` \- 浏览器客户端 API * `state-management-guide.md` \- 状态和 SQL 深入探讨 * `websockets-sse.md` \- WebSocket 与 SSE 比较 * `scheduling-api.md` \- 任务调度详细信息 * `workflows-integration.md` \- 工作流程指南 * `browser-rendering.md` \- 网页浏览模式 * `rag-patterns.md` \- RAG 最佳实践 * `mcp-server-guide.md` \- MCP 服务器开发 * `mcp-tools-reference.md` \- MCP 工具 API * `hitl-patterns.md` \- 人机交互工作流程 * `best-practices.md` \- 生产模式 ### 示例（示例/） * `chat-bot-complete.md` \- 完整聊天代理 * `multi-agent-workflow.md` \- 代理编排 * `scheduled-reports.md` \- 重复任务 * `browser-scraper-agent.md` \- 网页抓取 * `rag-knowledge-base.md` \- RAG系统 * `mcp-remote-server.md` \- 生产 MCP 服务器 ** ** **最后验证**：2025 年 10 月 21 日 **软件包版本**：agents@latest **合规性**：Cloudflare Agents SDK 官方文档

Cloudflare 代理

包含技能