Cloudflare Agents SDK 配置完全指南Wrangler 设置、绑定、路由与部署【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇指南以 Cloudflare Agents SDK 的配置文档为核心系统讲解如何在 Wrangler 中声明 Durable Object 绑定与迁移、定义类型安全的Env环境、通过routeAgent与routeAgentEmail组织多 Agent 与邮件路由并完成本地开发、生产部署与密钥管理。读完本文你将掌握一套可直接复制运行的 Agent 应用配置模板并能根据仓库内配套的 api.md、patterns.md 与 gotchas.md 进一步深入实现细节。Wrangler 基础配置声明 Agent 的 Durable ObjectCloudflare Agents SDK 构建在 Durable Objects 之上因此wrangler.jsonc的核心任务就是把每个 Agent 类注册为 Durable Object 绑定。一个最小可用的配置如下{ name: my-agents-app, durable_objects: { bindings: [ {name: MyAgent, class_name: MyAgent} ] }, migrations: [ {tag: v1, new_sqlite_classes: [MyAgent]} ], ai: { binding: AI } }逐项说明nameWorker 名称同时是部署到workers.dev的子域名与后续邮件路由中的目标 Worker 名。durable_objects.bindings将 Agent 类暴露给运行时。name是注入到Env中的绑定名class_name必须是 Worker 源码中导出的 Agent 类名例如MyAgent extends AgentEnv。若需跨 Worker 访问可参照 durable-objects/configuration.md 补充script_name指向外部 Worker。migrations声明 Durable Object 类的迁移记录。new_sqlite_classes表示首次创建带 SQLite 存储的类是官方推荐的方式对比旧的new_classesSQLite 更适合 Agent 的持久化状态。迁移 tag 必须唯一且递增v1、v2、v3……部署时自动应用不支持回滚生产环境可用npx wrangler deploy --dry-run先行校验。注意deleted_classes会立即销毁全部数据不可恢复。ai绑定 Workers AIbinding名约定为AI对应运行时注入的env.AI用于在 Agent 内执行模型推理。从源码结构看所有 Agent 类都继承了 Durable Object 的存储与状态能力详见 durable-objects/api.md因此这里的绑定配置直接决定了 Agent 的持久化存储、WebSocket 长连接与 SQLite 可用性。类型安全的 Env 环境绑定将全部绑定显式写入Env接口是官方推荐的最佳实践能让 Agent 内部的this.env.xxx访问获得完整的编译期类型检查interface Env { AI?: Ai; // Workers AI MyAgent?: DurableObjectNamespaceMyAgent; ChatAgent?: DurableObjectNamespaceChatAgent; DB?: D1Database; // D1 database KV?: KVNamespace; // KV storage R2?: R2Bucket; // R2 bucket OPENAI_API_KEY?: string; // Secrets GITHUB_CLIENT_ID?: string; // MCP OAuth credentials GITHUB_CLIENT_SECRET?: string; QUEUE?: Queue; // Queues }要点Durable Object 绑定类型为DurableObjectNamespaceAgentClass例如MyAgent?: DurableObjectNamespaceMyAgent。该命名空间提供了idFromName(name)、idFromString(id)、newUniqueId()与get(id)方法类型签名见 durable-objects/configuration.md。存储绑定D1 对应D1Database、KV 对应KVNamespace、R2 对应R2Bucket、队列对应Queue这些类型由cloudflare/workers-types提供。对应 wrangler 配置可参考 wrangler/configuration.md 中的d1_databases、kv_namespaces、r2_buckets、queues写法。密钥OPENAI_API_KEY、GITHUB_CLIENT_ID/SECRET等通过wrangler secret put注入属于加密存储的 Secrets不应写入配置文件。全部声明为可选?的好处是仅用到部分绑定的 Agent 或本地开发环境不会因缺少某个绑定而编译失败。部署命令本地开发、生产发布与密钥管理配置完成后通过 Wrangler CLI 完成全流程操作# Local dev npx wrangler dev # Deploy production npx wrangler deploy # Set secrets npx wrangler secret put OPENAI_API_KEYnpx wrangler dev启动本地开发服务器默认端口 8787支持热更新若需联调生产环境 Durable Object可加--remote见 durable-objects/configuration.md。npx wrangler deploy发布 Worker 并自动应用迁移。多环境部署可参考 wrangler 配置文档中的env块与--env production参数Durable Object 支持按环境隔离命名空间保证 staging 与 production 使用独立对象实例。npx wrangler secret put NAME以交互方式写入加密密钥环境变量自动注入到Env对应字段。CI/CD 场景中可改用CLOUDFLARE_API_TOKEN环境变量完成认证后执行npx wrangler deploy认证流程见 wrangler/auth.md。部署前建议先执行npx wrangler whoami确认已登录避免发布时因未认证失败。Agent 路由从自动路由到手动控制Worker 的fetch入口负责把 HTTP 请求分发给具体的 Agent 实例。官方推荐使用路由助手其次是手动路由高级场景。推荐routeAgent自动路由import { routeAgent } from agents; export default { fetch(request: Request, env: Env) { return routeAgent(request, env); } }routeAgent会基于 URL 模式自动将请求路由到对应的 Agent。其实现逻辑由 SDK 封装读者无需关心 URL 与 Agent 的映射细节当 Worker 中只有一个 Agent 绑定且未显式指定时请求会命中该 Agent 的onRequest等生命周期钩子生命周期详见 api.md。手动路由高级需要完全掌控请求分发时可自行解析 URL 并调用 Durable Object 的命名空间 APIexport default { async fetch(request: Request, env: Env) { const url new URL(request.url); // Named ID (deterministic) const id env.MyAgent.idFromName(user-123); // Random ID (from URL param) // const id env.MyAgent.idFromString(url.searchParams.get(id)); const stub env.MyAgent.get(id); return stub.fetch(request); } }两种 ID 生成方式的选择直接影响 Agent 的寻址模型idFromName(user-123)确定性寻址。同一名称永远映射到同一 Durable Object 实例适合一个用户一个 Agent每用户独立状态、独立 SQLite 存储的场景也是 React 客户端useAgent({ name: user-123 })的对应服务端逻辑。idFromString(...)从外部传入的 ID如 URL 参数恢复实例适合无状态网关转发或测试场景。多 Agent 设置按路径分流一个 Worker 可以同时承载多个 Agent通过路径前缀分流import { routeAgent } from agents; export default { fetch(request: Request, env: Env) { const url new URL(request.url); // Route by path if (url.pathname.startsWith(/chat)) { return routeAgent(request, env, ChatAgent); } if (url.pathname.startsWith(/task)) { return routeAgent(request, env, TaskAgent); } return new Response(Not found, { status: 404 }); } }routeAgent(request, env, ChatAgent)的第三个参数显式指定绑定的name使请求精确落到对应的 Agent 类。这种一 Worker 多 Agent 路径路由的布局是后续 patterns.md 中聊天 后台任务 邮件处理复合应用的基础。邮件路由让 Agent 直接处理邮件Agents SDK 允许 Agent 通过 Email Worker 接收并处理邮件需要代码与 Cloudflare 控制台两端配合。代码设置import { routeAgentEmail } from agents; export default { fetch: (req: Request, env: Env) routeAgent(req, env), email: (message: ForwardableEmailMessage, env: Env) { return routeAgentEmail(message, env); } }email处理器把收到的邮件交给routeAgentEmail由 SDK 负责把邮件投递到对应 Agent 的onEmail钩子。Dashboard 设置在 Cloudflare 控制台完成邮件路由绑定Destination: Workers with Durable Objects Worker: my-agents-app注意此处填入的 Worker 名必须与wrangler.jsonc中的name即my-agents-app完全一致否则投递失败。控制台会自动创建域名的 MX 与 SPF DNS 记录详见 email-routing/configuration.md。Agent 内处理邮件export class EmailAgent extends AgentEnv { async onEmail(email: AgentEmail) { const text await email.text(); // Process email } }onEmail收到的是AgentEmail对象可通过email.text()读取正文、email.from获取发件人、email.headers.get(subject)获取主题。进阶用法参考 patterns.md 中的邮件处理模式结合 SQL 落库、调用 AI 生成摘要、向 WebSocket 连接广播新邮件事件甚至用schedule安排自动回复。AI Gateway可选缓存与路由 AI 请求若希望为 AI 调用增加缓存与流量路由可经由 AI Gateway 发起 Workers AI 请求// Enable caching/routing through AI Gateway const response await this.env.AI.run( cf/meta/llama-3.1-8b-instruct, { prompt }, { gateway: { id: my-gateway-id, skipCache: false, cacheTtl: 3600 } } );参数说明idAI Gateway 的网关标识命名规范为小写字母数字加连字符如prod-api需先在控制台或通过 API 创建详见 ai-gateway/configuration.md。skipCache是否跳过缓存false表示启用缓存。cacheTtl缓存 TTL秒此处3600即缓存 1 小时适用于重复性高的推理请求以节省成本与延迟。从 gotchas.md 可以注意到一个配套实践AI 服务可能超时或超出配额生产环境应对env.AI.run包裹try/catch并提供降级方案避免 Agent 整体失败。MCP 配置可选为 Agent 暴露工具通过 Model Context ProtocolMCP可以把 Agent 的能力暴露给外部 AI 系统或在 Agent 内注册远程 MCP 服务器以获取外部工具。配置分两步第一步Wrangler 变量与密钥// wrangler.jsonc - Add MCP OAuth secrets { vars: { MCP_SERVER_URL: https://mcp.example.com } } // Set secrets via CLI // npx wrangler secret put GITHUB_CLIENT_ID // npx wrangler secret put GITHUB_CLIENT_SECRETMCP_SERVER_URL作为普通变量vars注入供 Agent 代码读取OAuth 客户端凭据GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET则以密钥形式通过 CLI 写入与OPENAI_API_KEY相同的secret put流程避免明文入库。第二步Agent 代码注册在 Agent 代码中注册并消费 MCP 服务器对应 api.md 的 MCP 章节// 在 Agent 内注册 await this.mcp.registerServer(github, { url: env.MCP_SERVER_URL, auth: { type: oauth, clientId: env.GITHUB_CLIENT_ID, clientSecret: env.GITHUB_CLIENT_SECRET } }); // 拉取工具并注入 streamText const tools await this.mcp.getAITools([github]); return this.streamText({ model: openai(gpt-4), messages: this.messages, tools, onFinish });有一个值得注意的实现细节见 gotchas.mdMCP 服务器连接在 Durable Object 休眠后不会自动存活因此生产环境应在onStart()中重新注册 MCP 服务器并对 MCP 请求实现重试/退避逻辑。配套参考与深度阅读本文覆盖了 Agents SDK 配置面的全部核心内容。继续深入时仓库内同一目录的配套文档值得依次阅读agents-sdk/api.mdAIChatAgent/Agent类、生命周期钩子onStart、onRequest、onConnect、onMessage、onEmail、状态与 SQL、调度、callableRPC、客户端 Hooks。agents-sdk/patterns.mdAI 聊天带工具、人类在环客户端工具、任务队列与定时处理、手动 WebSocket 聊天、邮件 AI 处理、实时协作等完整模式。agents-sdk/gotchas.md常见错误与限额表例如每个 Agent 最多 1000 个调度任务、实例内存 128MB、单条 SQL 行 2MB、WebSocket 消息上限 32MiB、单实例约 1000 req/s 等是配置容量规划的重要依据。durable-objects/configuration.mdDurable Object 绑定选项、迁移规则、环境隔离、地域jurisdiction与durable-objects管理命令。wrangler/configuration.mdwrangler.jsonc全字段参考包括变量、存储绑定、路由、静态资源与运行限制。掌握本文的 Wrangler 声明、类型化Env、路由与部署流程后即可进入 Agents SDK 的 API 层编写真正的 Agent 业务逻辑。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
