Cloudflare Agents SDK
Use current Cloudflare documentation and the installed agents package as the
contract. APIs in this SDK evolve quickly; do not trust remembered signatures or
examples without checking the relevant version.
Inspect first
- Read the project's package version, Wrangler configuration, Agent exports,
routing entrypoint, and generated binding types.
- Retrieve the current docs for the feature being changed.
- Inspect installed exports and
.d.ts files before adding casts or adapters.
- Identify the Agent instance name and who is authorized to select it. Instance
naming is a state-partition and access-control decision, not just a URL detail.
Agents require Durable Objects. Verify the exact class export, binding, and
lifecycle declaration used by the target environment. Do not copy a migration
or configuration example without checking the current lifecycle model.
Preserve the runtime contract
- Treat persisted Agent state, connection state, scheduled work, and client UI
state as separate surfaces.
- Validate client-originated state and callable methods at the server boundary;
a callable method is not authorization by itself.
- Use stable operation identities for work that may be retried or resumed.
- Distinguish ordinary request work from SDK durable-execution primitives. Use
the latter only when work must survive Durable Object eviction or restart.
- Expect the Agent constructor and in-memory state to be recreated. Persist
anything required after eviction.
- Keep routing and client naming consistent. Test the actual route through
routeAgentRequest or the project's custom router.
- Treat experimental integrations as version-specific. Pin and test the seam
rather than spreading preview types through domain code.
Load only the relevant reference
| Need |
Reference |
| State, SQL, schedules, or alarms |
state-scheduling.md |
| Callable RPC, streaming, or timeouts |
callable.md |
| Routing, bindings, or project setup |
routing.md, configuration.md |
| React/browser clients or chat streaming |
client-sdk.md, streaming-chat.md |
| Server-driven turns or approval flows |
server-driven-messages.md, human-in-the-loop.md |
| Workflows, fibers, queues, or retries |
workflows.md, durable-execution.md, queue-retries.md |
| MCP, email, webhooks, push, or observability |
mcp.md, email.md, webhooks-push.md, observability.md |
| Preview features |
think.md, voice.md, codemode.md, browse-the-web.md |
Read current first-party docs before relying on limits, package names,
configuration fields, or experimental availability.
Verify proportionally
Run the narrow type, route, and state tests for the changed seam. For connection
or recovery behavior, test disconnect/reconnect and a recreated Agent instance.
For scheduled or durable work, prove that duplicate delivery converges and that
the persisted result—not an in-memory flag—defines completion.
1---2name: agents-sdk3description: Build or debug stateful applications that specifically use Cloudflare's `agents` package, including Agent classes, routing, callable methods, synchronized state, scheduling, AIChatAgent, durable execution, or Agents SDK client hooks. Do not trigger for generic AI-agent design, the OpenAI Agents SDK, or ordinary Durable Object work that does not use the Cloudflare Agents SDK.4metadata:5 source: https://skillmd.com/skills/swyxio/agents-sdk6---78# Cloudflare Agents SDK910Use current Cloudflare documentation and the installed `agents` package as the11contract. APIs in this SDK evolve quickly; do not trust remembered signatures or12examples without checking the relevant version.1314## Inspect first15161. Read the project's package version, Wrangler configuration, Agent exports,17 routing entrypoint, and generated binding types.182. Retrieve the current docs for the feature being changed.193. Inspect installed exports and `.d.ts` files before adding casts or adapters.204. Identify the Agent instance name and who is authorized to select it. Instance21 naming is a state-partition and access-control decision, not just a URL detail.2223Agents require Durable Objects. Verify the exact class export, binding, and24lifecycle declaration used by the target environment. Do not copy a migration25or configuration example without checking the current lifecycle model.2627## Preserve the runtime contract2829- Treat persisted Agent state, connection state, scheduled work, and client UI30 state as separate surfaces.31- Validate client-originated state and callable methods at the server boundary;32 a callable method is not authorization by itself.33- Use stable operation identities for work that may be retried or resumed.34- Distinguish ordinary request work from SDK durable-execution primitives. Use35 the latter only when work must survive Durable Object eviction or restart.36- Expect the Agent constructor and in-memory state to be recreated. Persist37 anything required after eviction.38- Keep routing and client naming consistent. Test the actual route through39 `routeAgentRequest` or the project's custom router.40- Treat experimental integrations as version-specific. Pin and test the seam41 rather than spreading preview types through domain code.4243## Load only the relevant reference4445| Need | Reference |46| --- | --- |47| State, SQL, schedules, or alarms | [state-scheduling.md](references/state-scheduling.md) |48| Callable RPC, streaming, or timeouts | [callable.md](references/callable.md) |49| Routing, bindings, or project setup | [routing.md](references/routing.md), [configuration.md](references/configuration.md) |50| React/browser clients or chat streaming | [client-sdk.md](references/client-sdk.md), [streaming-chat.md](references/streaming-chat.md) |51| Server-driven turns or approval flows | [server-driven-messages.md](references/server-driven-messages.md), [human-in-the-loop.md](references/human-in-the-loop.md) |52| Workflows, fibers, queues, or retries | [workflows.md](references/workflows.md), [durable-execution.md](references/durable-execution.md), [queue-retries.md](references/queue-retries.md) |53| MCP, email, webhooks, push, or observability | [mcp.md](references/mcp.md), [email.md](references/email.md), [webhooks-push.md](references/webhooks-push.md), [observability.md](references/observability.md) |54| Preview features | [think.md](references/think.md), [voice.md](references/voice.md), [codemode.md](references/codemode.md), [browse-the-web.md](references/browse-the-web.md) |5556Read current first-party docs before relying on limits, package names,57configuration fields, or experimental availability.5859## Verify proportionally6061Run the narrow type, route, and state tests for the changed seam. For connection62or recovery behavior, test disconnect/reconnect and a recreated Agent instance.63For scheduled or durable work, prove that duplicate delivery converges and that64the persisted result—not an in-memory flag—defines completion.