一页放下一本书最常查的东西。打印出来贴墙上也行。
本版按 Project Think + Agents Week 2026 更新;旧的 Agent / AIChatAgent 钩子仍兼容,Think 是它们的超集。
橙色是控制 / 边界 primitive(Access、限流、灰度、观测、MCP 暴露、sub-agent),其余是 agent 直接调的下游能力。
| Binding | 一句话 | wrangler.jsonc 片段 |
|---|
| AI(unified) | Workers AI + 70+ 第三方模型,同一个 binding | "ai": { "binding": "AI" } |
| Durable Object | Think / Agent 实例本体 | "durable_objects": { "bindings": [{ "name": "CODER_AGENT", "class_name": "CoderAgent" }] } |
| 迁移(必配) | 声明哪些 DO class 用 SQLite | "migrations": [{ "tag": "v1", "new_sqlite_classes": ["CoderAgent"] }] |
| Containers | Sandbox 容器 | "containers": [{ "class_name": "Sandbox", "image": "./Dockerfile" }] |
| Worker Loader | Code Mode / 扩展 用 | "worker_loaders": [{ "binding": "LOADER" }] |
| Artifacts | git for agents(beta) | "artifacts": [{ "binding": "ARTIFACTS", "namespace": "default" }] |
| Memory(私测) | 托管长期记忆 | "memory": [{ "binding": "MEMORY" }] // 待验证 字段名 |
| Workflows v2 | 多步可恢复 | "workflows": [{ "name": "solve-issue", "binding": "SOLVE_ISSUE", "class_name": "SolveIssue" }] |
| Browser Run | CDP / Live View / quick actions | "browser": { "binding": "BROWSER" } |
| Email Send | 出站邮件(public beta) | "send_email": [{ "name": "EMAIL", "remote": true }] |
| R2 / KV / D1 / Vectorize | 存储与检索 | 沿用旧字段 |
| Rate Limiter | 滑动窗口(beta,unsafe) | { "name": "RATE_LIMITER", "type": "ratelimit", "namespace_id": "1001", "simple": { "limit": 60, "period": 60 } } |
| Mesh / VPC | onprem / 跨云内网 | "vpc_networks": [{ "binding": "MESH", "network_id": "cf1:network", "remote": true }] |
| Flagship(beta) | feature flag binding | "flagship": [{ "binding": "FLAGSHIP", "app_id": "<APP_ID>" }] |
| Secrets | 命令行 | npx wrangler secret put X [--env production] |
| Tail consumer | 旁路日志 | "tail_consumers": [{ "service": "agent-coder-tail" }] |
| Hook / 字段 | 触发时机 / 用途 |
|---|
getModel() | 必须 override,返一个 AI SDK LanguageModel |
getSystemPrompt() | 默认 "You are a helpful assistant.",可 async |
getTools() | 返 ToolSet(createWorkspaceTools(this.workspace) 起步) |
configureSession(session) | session.withContext(...).withCachedPrompt() 等 |
getExtensions() | 启用扩展沙盒(需 extensionLoader) |
beforeTurn(ctx) | 一轮 LLM 调用前(限流、按 plan 切 model) |
beforeStep(ctx) | 每个 step 前(动态选 model / tools) |
beforeToolCall(ctx) | 工具调用前,可 {action: "allow"|"block"|"substitute"} |
afterToolCall(ctx) | 工具调用后(净化输出) |
onStepFinish(ctx) | 一个 step 完成 |
onChunk(ctx) | 每 token,慎用 |
onChatResponse / onChatError / onChatRecovery | 整轮收尾 / 出错 / 恢复 |
chat(msg, cb, opts?) | 子代理 RPC 入口 |
saveMessages / continueLastTurn / clearMessages / getMessages | 消息操作 |
configure<T> / getConfig<T> | 持久化私有配置(think_config 表) |
subAgent / abortSubAgent / hasSubAgent / listSubAgents / parentAgent | DO Facets 子代理 |
runWorkflow / onWorkflowProgress / onWorkflowComplete | Workflows v2 联动 |
schedule / cancelSchedule / keepAlive | 定时与持久化 fiber |
完整签名见 developers.cloudflare.com/agents/api-reference/think/。
| API | 用途 |
|---|
getSandbox(ns, id, opts?) | 拿到 stub(sleepAfter 默认 "10m",transport 默认 "http") |
sb.exec(cmd, opts?) / execStream | 一次性命令 / 流式 |
sb.startProcess(cmd, opts?, sid?) | 长进程(返 Process) |
sb.gitCheckout(url, { branch?, targetDir?, depth? }) | 克隆 |
sb.writeFile / readFile / readFileStream / watch | 文件 IO + inotify 监听 |
sb.exposePort(port, { hostname }) | 暴露端口,返 { url } |
sb.terminal(req, opts?) | PTY(WebSocket Upgrade) |
sb.createCodeContext / runCode / runCodeStream | Python/JS/TS 持久解释器 |
sb.createBackup / restoreBackup | squashfs → R2 备份 |
sb.mountBucket(bucket, path, opts) | s3fs FUSE 挂 R2 |
proxyToSandbox(req, env) | Worker 入口路由 |
proxyTerminal(stub, sid, req, opts?) | PTY 代理 |
static outboundByHost = {...} | egress 拦截 // 待验证(blog 给的写法,d.ts 未列) |
| API | 用途 |
|---|
create(name, { readOnly?, description?, setDefaultBranch? }) | 新建,返 { name, remote, token } |
get(name) | 拿到 ArtifactsRepo,不存在抛错 |
list({ limit?, cursor? }) | 列出,每条带 status: "ready"|"importing"|"forking" |
import({ source: { url, branch?, depth? }, target: { name, opts? } }) | 从外部 git 导入 |
delete(name) | 删 |
repo.fork(name, opts?) | 派生 |
repo.createToken(scope?, ttl?) / listTokens() / revokeToken(t) | token 管理 |
容器内拼 clone URL:https://x:${TOKEN}@<id>.artifacts.cloudflare.net/git/<ns>/<repo>.git,token 自带 ?expires= 后缀。
| 维度 | v1 | v2 |
|---|
| 并发 instance / account | 4 500 | 50 000 |
| 创建速率 / account | 100/s | 300/s |
| 队列长度 / workflow | 1 M | 2 M |
| 架构 | 单 Account | + SousChef + Gatekeeper |
| step API | step.do / sleep / sleepUntil / waitForEvent | 未变 |
| Agents 集成 | 手写 binding | AgentWorkflow + step.sendEvent + step.waitForApproval |
step API 没破坏性变化;v2 升级对老代码透明,直接享受新限额。
env.AI.run("@cf/meta/llama-3.3-70b-instruct-fp8-fast", { prompt }) // Workers AI
env.AI.run("anthropic/claude-opus-4-6", { prompt }) // Anthropic
env.AI.run("openai/gpt-4o", { prompt }) // OpenAI
env.AI.run("google/gemini-2.5-pro", { prompt }) // Google
env.AI.run("bytedance/seed-1.6", { prompt }) // Bytedance
// 第三参数:挂 AI Gateway → 计费 / 缓存 / 自动 failover
env.AI.run("anthropic/claude-haiku-4-5", { prompt }, { gateway: { id: "agent-coder" } })
可用 provider:Anthropic / OpenAI / Google / Alibaba / Bytedance / AssemblyAI / InWorld / MiniMax / Pixverse / Recraft / Runway / Vidu(2026-04 名单)。Multimodal input shape 各家不同,// 待验证。
| Primitive | 一句话 |
|---|
| Cloudflare Mesh | Worker 进 VPC;vpc_networks binding + cf1:network 关键字,env.MESH.fetch("http://10.0.1.50/...") 直连内网 |
| Managed OAuth for Access | Access App 一键开 OAuth,RFC 9728 + 9727 + 7591(DCR) + 7636(PKCE);agent 收到 401 自动走授权流,后续带 user JWT |
| Flagship | OpenFeature 兼容的 feature flag binding(env.FLAGSHIP.getStringValue("name", "default", { targetingKey, plan })),子毫秒评估,规则可配 AND/OR 嵌套 |
| API | 用途 |
|---|
useAgent({ agent, name }) | React,WebSocket + state 同步 |
useAgentChat({ agent }) | 在 useAgent 之上的 chat hook(@cloudflare/ai-chat/react) |
agentFetch(req, opts) | 不用 hook 的 HTTP 版 |
AgentClient | 框架无关的 WebSocket client |
| 维度 | 数字 |
|---|
| 单 agent SQLite 存储 | 1 GB |
| 单 agent CPU 时间 | 30 秒(每个 HTTP 请求 / 入站消息 / scheduled 都刷新) |
| 单 step 墙钟 | 不限 |
| WebSocket 单消息 | 1 MB |
| 同时活跃 WS / DO | 32k |
| Sandbox 并发(2026 GA) | lite ≤ 15 000;basic ≤ 6 000;large ≤ 1 000+(可申请) |
| Sandbox 实例规模 | instance_type: "lite" | "basic" | "large"(// 待验证 字段名) |
| Sandbox 定价 | Active CPU Pricing(只算活跃 CPU);具体 $/sec 官网 // 待验证 |
| Workflows v2 并发 | 50 000 / account;创建 300/s;队列 2M / workflow |
| Browser Run 并发 | 120 / account(从 30 升,2026) |
| Artifacts 定价 | beta 期免费 / 待公开 // 待验证 |
| 现象 | 原因 / 怎么修 |
|---|
404 在 /agents/... | routeAgentRequest 未挂 / worker 没 export { CoderAgent } |
7003 Could not route to... | DO 找不到。检查 class_name 拼写、re-export、new_sqlite_classes |
SQL was not enabled for this Durable Object | 写成了 new_classes。Think / Agent 必须用 SQLite,改成 new_sqlite_classes 出新 tag |
| Think 提示 “extension loader missing” | getExtensions() 用了但没配 worker_loaders |
createSandboxTools 返空 | 0.4 还是占位实现,沙盒工具自己包(直接调 @cloudflare/sandbox RPC) |
env.MESH.fetch 解析不到 host | 走的是公网域名;Mesh 只解 Mesh 内部地址 / *.mesh |
env.FLAGSHIP 是 undefined | 你的账户没在 Flagship beta 白名单 |
env.AI.run("anthropic/...") 401 | AI Gateway 没绑 provider key,或 gateway id 写错 |
| WebSocket 连接立刻断 code 4001 | onConnect 鉴权没过(本书第 10 章约定的 close code) |
experimentalDecorators 报错 | 删掉;Agents / Think 用 TC39 标准装饰器 |
# 项目骨架
npm create cloudflare@latest -- agent-coder --template=cloudflare/agents-starter --no-deploy
# 类型生成
npx wrangler types env.d.ts --include-runtime false
# 本地跑
npx wrangler dev
# Secret(注意 --env)
npx wrangler secret put ANTHROPIC_API_KEY --env production
# 部署
npx wrangler deploy --env staging
npx wrangler deploy --env production
# 灰度(粗粒度,精细灰度用 Flagship)
npx wrangler versions upload --env production
npx wrangler versions deploy --env production
# 回滚 / 实时日志
npx wrangler rollback --env production
npx wrangler tail --env production
# Browser Run
npx wrangler browser create --keepAlive 300
# MCP 自检
npx @modelcontextprotocol/inspector https://agents.example.com/mcp