Agents SDK v0.5.0: Protocol message control, retry utilities, data parts, and @cloudflare/ai-chat v0.1.0

The latest release of the Agents SDK adds built-in retry utilities, per-connection protocol message control, and a fully rewritten @cloudflare/ai-chat with data parts, tool approval persistence, and zero breaking changes.

Retry utilities

A new this.retry() method lets you retry any async operation with exponential backoff and jitter. You can pass an optional shouldRetry predicate to bail early on non-retryable errors.

class MyAgent extends Agent { async onRequest(request) { const data = await this.retry(() => callUnreliableService(), { maxAttempts: 4, shouldRetry: (err) => !(err instanceof PermanentError), }); return Response.json(data); } }

class MyAgent extends Agent { async onRequest(request: Request) { const data = await this.retry(() => callUnreliableService(), { maxAttempts: 4, shouldRetry: (err) => !(err instanceof PermanentError), }); return Response.json(data); } }

Retry options are also available per-task on queue(), schedule(), scheduleEvery(), and addMcpServer():

// Per-task retry configuration, persisted in SQLite alongside the task await this.schedule( Date.now() + 60_000, "sendReport", { userId: "abc" }, { retry: { maxAttempts: 5 }, }, ); // Class-level retry defaults class MyAgent extends Agent { static options = { retry: { maxAttempts: 3 }, }; }

// Per-task retry configuration, persisted in SQLite alongside the task await this.schedule(Date.now() + 60_000, "sendReport", { userId: "abc" }, { retry: { maxAttempts: 5 }, }); // Class-level retry defaults class MyAgent extends Agent { static options = { retry: { maxAttempts: 3 }, }; }

Retry options are validated eagerly at enqueue/schedule time, and invalid values throw immediately. Internal retries have also been added for workflow operations (terminateWorkflow, pauseWorkflow, and others) with Durable Object-aware error detection.

Per-connection protocol message control

Agents automatically send JSON text frames (identity, state, MCP server lists) to every WebSocket connection. You can now suppress these per-connection for clients that cannot handle them — binary-only devices, MQTT clients, or lightweight embedded systems.

class MyAgent extends Agent { shouldSendProtocolMessages(connection, ctx) { // Suppress protocol messages for MQTT clients const subprotocol = ctx.request.headers.get("Sec-WebSocket-Protocol"); return subprotocol !== "mqtt"; } }

class MyAgent extends Agent { shouldSendProtocolMessages(connection: Connection, ctx: ConnectionContext) { // Suppress protocol messages for MQTT clients const subprotocol = ctx.request.headers.get("Sec-WebSocket-Protocol"); return subprotocol !== "mqtt"; } }