企业官网建设流程全解析

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 Object

Cloudflare 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" } }

逐项说明：

• name：Worker 名称，同时是部署到workers.dev的子域名与后续邮件路由中的目标 Worker 名。
• durable_objects.bindings：将 Agent 类暴露给运行时。name是注入到Env中的绑定名，class_name必须是 Worker 源码中导出的 Agent 类名（例如MyAgent extends Agent<Env>）。若需跨 Worker 访问，可参照 durable-objects/configuration.md 补充script_name指向外部 Worker。
• migrations：声明 Durable Object 类的迁移记录。new_sqlite_classes表示首次创建带 SQLite 存储的类，是官方推荐的方式（对比旧的new_classes，SQLite 更适合 Agent 的持久化状态）。迁移 tag 必须唯一且递增（v1、v2、v3……），部署时自动应用，不支持回滚，生产环境可用npx wrangler deploy --dry-run先行校验。注意deleted_classes会立即销毁全部数据，不可恢复。
• ai：绑定 Workers AI，binding名约定为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?: DurableObjectNamespace<MyAgent>; ChatAgent?: DurableObjectNamespace<ChatAgent>; 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 绑定类型为DurableObjectNamespace<AgentClass>，例如MyAgent?: DurableObjectNamespace<MyAgent>。该命名空间提供了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_KEY

• npx 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 的命名空间 API：

export 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 Agent<Env> { 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 } } );

参数说明：

• id：AI 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 Protocol（MCP）可以把 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_SECRET

MCP_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.md）：MCP 服务器连接在 Durable Object 休眠后不会自动存活，因此生产环境应在onStart()中重新注册 MCP 服务器，并对 MCP 请求实现重试/退避逻辑。

配套参考与深度阅读

本文覆盖了 Agents SDK 配置面的全部核心内容。继续深入时，仓库内同一目录的配套文档值得依次阅读：

• agents-sdk/api.md：AIChatAgent/Agent类、生命周期钩子（onStart、onRequest、onConnect、onMessage、onEmail）、状态与 SQL、调度、@callableRPC、客户端 Hooks。
• agents-sdk/patterns.md：AI 聊天带工具、人类在环（客户端工具）、任务队列与定时处理、手动 WebSocket 聊天、邮件 AI 处理、实时协作等完整模式。
• agents-sdk/gotchas.md：常见错误与限额表，例如每个 Agent 最多 1000 个调度任务、实例内存 128MB、单条 SQL 行 2MB、WebSocket 消息上限 32MiB、单实例约 1000 req/s 等，是配置容量规划的重要依据。
• durable-objects/configuration.md：Durable Object 绑定选项、迁移规则、环境隔离、地域（jurisdiction）与durable-objects管理命令。
• wrangler/configuration.md：wrangler.jsonc全字段参考，包括变量、存储绑定、路由、静态资源与运行限制。

掌握本文的 Wrangler 声明、类型化Env、路由与部署流程后，即可进入 Agents SDK 的 API 层，编写真正的 Agent 业务逻辑。

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills