agents-sdk

agents-sdk 技能概览

agents-sdk 适合做什么

agents-sdk 技能可以帮助你在需要有状态对话、持久化执行、WebSocket 或实时交互、定时任务、MCP 集成，或基于浏览器的自动化时，使用 Agents SDK 构建基于 Cloudflare Workers 的 agent。对于想做安装决策的人来说，agents-sdk skill 最适合拿来判断：这个 SDK 能不能胜任、需要哪些配置、编码前应该先读什么。

最适合的使用场景

当你要创建一个生产级 Worker，并且它需要持久化 agent 状态、可调用方法、类型化的客户端访问、队列驱动的工作流、重试、可观测性，或者 React 客户端 hooks 时，就适合用 agents-sdk。如果这些 agents 运行在 Cloudflare 的运行时里，并且共享 Worker / Durable Object 的约束，那么 agents-sdk for Multi-Agent Systems 也很适合。

它和其他方案有什么不同

这个技能不是一个泛泛的“帮我构建 agent”提示词。它和 Cloudflare 的具体实现细节绑定得很紧：Durable Objects、wrangler.jsonc、migrations、nodejs_compat，以及 @callable()、runFiber、useAgent 这类 API 特定模式。因此，真正的上手风险主要是配置，而不是概念设计。

如何使用 agents-sdk 技能

安装并确认上下文正确

先用 skills manager 执行 agents-sdk install 步骤，然后确认你处理的是 Cloudflare Workers 仓库，而不是一个独立的聊天应用。基础安装方式如下：

npx skills add cloudflare/skills --skill agents-sdk

安装完成后，先读 SKILL.md，再优先查看 references/configuration.md、references/client-sdk.md、references/callable.md 和 references/durable-execution.md。这些文件会回答最常卡住落地的几个问题：bindings、migrations、客户端连接，以及状态如何在重启后继续存在。

把模糊目标改写成有用的提示词

当你的提示词不仅说功能，还明确 runtime 形态时，这个技能的效果会更好。更好的输入应包括：

• agent 类型：聊天 agent、工作流 agent、语音 agent、浏览器 agent，或者 MCP server
• 是新项目，还是加到现有 Workers 应用里
• 客户端形态：React hook、普通 JS client、RPC、email，或 WebSocket
• 持久化需求：简单状态、持久化执行，还是队列 / 重试流程

更强的 agents-sdk usage 请求示例：
“添加一个 Cloudflare Worker agent，按用户保存状态，暴露一个 callable 方法，并通过 React client 流式返回聊天响应。请使用当前的 Agents SDK 配置规则，并展示所需的 wrangler.jsonc 修改。”

按正确顺序阅读仓库

对大多数安装场景来说，最有价值的阅读路径是：

1. SKILL.md：支持的模式和检索来源
2. references/configuration.md：bindings、migrations 和本地开发设置
3. references/callable.md 和 references/client-sdk.md：客户端 / 服务端交互
4. 如果应用需要持久化或长任务，再看 references/state-scheduling.md、references/workflows.md 或 references/durable-execution.md
5. 如果可靠性很重要，再看 references/observability.md 和 references/queue-retries.md

会明显影响输出质量的实用建议

把你现有的 wrangler.jsonc、当前 agent class 名称，以及新代码应放置的精确路径都给技能。也请说明你是否已经在用 React、Workers AI 或 MCP。另外要说明你需要的是最小可运行示例，还是集成补丁，因为这两种目标对应的 SDK 配置细节差异很大。

agents-sdk 技能常见问题

agents-sdk 只适合新项目吗？

不是。agents-sdk guide 同时支持新的 Workers 应用和现有项目，但老仓库需要更仔细地检查配置。如果你已经有 bindings、migrations 或自定义构建栈，最好一开始就把这些信息提供出来，这样技能才能贴合现有设置。

我需要先懂 Cloudflare 吗？

有基础的 Cloudflare 认知会有帮助，不过只要你能按照配置说明操作，并读懂 wrangler.jsonc，这个技能就能用。初学者通常可以从一个很窄的目标开始，比如单个 agent 加一条客户端路径，而不是一上来就做完整的多 agent 系统。

什么时候不该用 agents-sdk？

如果你只需要无状态 API 包装、单次 LLM 调用，或者一个不依赖 Cloudflare 运行时、与 provider 无关的 chatbot，就不要用 agents-sdk。如果你无法使用 Durable Objects、Workers 的约束，或者 Cloudflare 特定的部署流程，它也不是合适选择。

这和普通 prompt 有什么区别？

普通 prompt 可能只是概念性地描述一个 agent，而 agents-sdk 是建立在 Cloudflare 真实 API 表面和部署规则之上的。这能减少你在 @callable()、状态、migrations 和客户端 hooks 上的猜测，而这些正是通用建议最容易失灵的地方。

如何改进 agents-sdk 技能

给出准确的部署形态

提升效果最大的方式，是明确说明 agent 是跑在单个 Worker 里、使用多个 Durable Object class、暴露 RPC，还是需要浏览器 / MCP 集成。如果你想要更好的 agents-sdk usage，就不要只说“构建一个 agent”，而要补充预期入口、事件源和状态模型。

提供配置和约束细节

最常见的失败模式，是 Cloudflare 上下文不完整。请提供你的 wrangler.jsonc、compatibility flags、Durable Object bindings、migration 状态，以及任何本地开发要求。如果技能能看到这些约束，就可以避开那些会破坏部署的建议。

先从可运行的最小切片开始迭代

先要求一条窄而完整的端到端路径：安装、配置、一个 agent class、一次 client 调用、一次状态更新。等第一条路径跑通后，再扩展到 queues、workflows、streaming 或 observability。这是验证 agents-sdk skill 是否适合你的应用、并尽早发现 bindings 或 runtime 假设不匹配的最快方式。