Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR was opened by the Changesets release GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated.
Releases
[email protected]
Patch Changes
#825
0c3c9bbThanks @threepointone! - Add cursor-based pagination togetWorkflows(). Returns aWorkflowPagewith workflows, total count, and cursor for next page. Default limit is 50 (max 100).#825
0c3c9bbThanks @threepointone! - Add workflow control methods:terminateWorkflow(),pauseWorkflow(),resumeWorkflow(), andrestartWorkflow().#799
d1a0c2bThanks @threepointone! - feat: Add Cloudflare Workflows integration for AgentsAdds seamless integration between Cloudflare Agents and Cloudflare Workflows for durable, multi-step background processing.
Why use Workflows with Agents?
Agents excel at real-time communication and state management, while Workflows excel at durable execution. Together:
AgentWorkflow Base Class
Extend
AgentWorkflowinstead ofWorkflowEntrypointto get typed access to the originating Agent:Agent Methods
runWorkflow(workflowName, params, options?)- Start workflow with optional metadata for queryingsendWorkflowEvent(workflowName, workflowId, event)- Send events to waiting workflowsgetWorkflow(workflowId)- Get tracked workflow by IDgetWorkflows(criteria?)- Query by status, workflowName, or metadata with paginationdeleteWorkflow(workflowId)- Delete a workflow tracking recorddeleteWorkflows(criteria?)- Delete workflows by criteria (status, workflowName, metadata, createdBefore)approveWorkflow(workflowId, data?)- Approve a waiting workflowrejectWorkflow(workflowId, data?)- Reject a waiting workflowAgentWorkflow Methods
On
this(non-durable, lightweight):reportProgress(progress)- Report typed progress object to AgentbroadcastToClients(message)- Broadcast to WebSocket clientswaitForApproval(step, opts?)- Wait for approval (throws on rejection)On
step(durable, idempotent):step.reportComplete(result?)- Report successful completionstep.reportError(error)- Report an errorstep.sendEvent(event)- Send custom event to Agentstep.updateAgentState(state)- Replace Agent state (broadcasts to clients)step.mergeAgentState(partial)- Merge into Agent state (broadcasts to clients)step.resetAgentState()- Reset Agent state to initialState (broadcasts to clients)Lifecycle Callbacks
Override these methods to handle workflow events (workflowName is first for easy differentiation):
Workflow Tracking
Workflows are automatically tracked in
cf_agents_workflowsSQLite table:metadatafield for queryable key-value dataSee
docs/workflows.mdfor full documentation.#812
6218541Thanks @threepointone! - # Bug FixesThis release includes three bug fixes:
1. Hung Callback Detection in scheduleEvery()
Fixed a deadlock where if an interval callback hung indefinitely, all future interval executions would be skipped forever.
Fix: Track execution start time and force reset after 30 seconds of inactivity. If a previous execution appears hung (started more than 30s ago), it is force-reset and re-executed.
2. Corrupted State Recovery
Fixed a crash when the database contains malformed JSON state.
Fix: Wrapped
JSON.parsein try-catch with fallback toinitialState. If parsing fails, the agent logs an error and recovers gracefully.3. getCallableMethods() Prototype Chain Traversal
Fixed
getCallableMethods()to find@callablemethods from parent classes, not just the immediate class.Fix: Walk the full prototype chain using
Object.getPrototypeOf()loop.#812
6218541Thanks @threepointone! - # Callable System ImprovementsThis release includes several improvements to the
@callabledecorator and RPC system:New Features
Client-side RPC Timeout
You can now specify a timeout for RPC calls that will reject if the call doesn't complete in time:
StreamingResponse.error()
New method to gracefully signal an error during streaming and close the stream:
getCallableMethods() API
New method on the Agent class to introspect all callable methods and their metadata:
Connection Close Handling
Pending RPC calls are now automatically rejected with a "Connection closed" error when the WebSocket connection closes unexpectedly.
Internal Improvements
callableMetadatafromMaptoWeakMapto prevent memory leaks when function references are garbage collected.Math.random().toString(36)withcrypto.randomUUID()for more robust and unique RPC call identifiers.API Enhancements
The
agent.call()method now accepts a unifiedCallOptionsobject with timeout support:Both formats work seamlessly - the client auto-detects which format you're using.
#812
6218541Thanks @threepointone! - feat: AddscheduleEverymethod for fixed-interval schedulingAdds a new
scheduleEvery(intervalSeconds, callback, payload?)method to the Agent class for scheduling recurring tasks at fixed intervals.Features
cancelSchedule(id)to stop the recurring scheduleUsage
Querying interval schedules
Schema changes
Adds
intervalSecondsandrunningcolumns tocf_agents_schedulestable (auto-migrated for existing agents).#812
6218541Thanks @threepointone! - AddisAutoReplyEmail()utility to detect auto-reply emailsDetects auto-reply emails based on standard RFC 3834 headers (
Auto-Submitted,X-Auto-Response-Suppress,Precedence). Use this to avoid mail loops when sending automated replies.#781
fd79481Thanks @HueCodes! - fix: properly type tool error content in getAITools#812
6218541Thanks @threepointone! - fix: improve type inference for RPC methods returning custom interfacesPreviously,
RPCMethodused{ [key: string]: SerializableValue }to check if return types were serializable. This didn't work with TypeScript interfaces that have named properties (likeinterface CoreState { counter: number; name: string; }), causing those methods to be incorrectly excluded from typed RPC calls.Now uses a recursive
CanSerialize<T>type that checks if all properties of an object are serializable, properly supporting:Also expanded
NonSerializableto explicitly exclude non-JSON-serializable types likeDate,RegExp,Map,Set,Error, and typed arrays.#825
0c3c9bbThanks @threepointone! - Fix workflow tracking table not being updated by AgentWorkflow callbacks.Previously, when a workflow reported progress, completion, or errors via callbacks, the
cf_agents_workflowstracking table was not updated. This causedgetWorkflow()andgetWorkflows()to return stale status (e.g., "queued" instead of "running" or "complete").Now,
onWorkflowCallback()automatically updates the tracking table:completed_attimestampFixes Workflow Tracking Table Not Updated by AgentWorkflow Callbacks #821.
#812
6218541Thanks @threepointone! - feat: Add options-based API foraddMcpServerAdds a cleaner options-based overload for
addMcpServer()that avoids passingundefinedfor unused positional parameters.Before (still works)
After (preferred)
Options
The legacy 5-parameter signature remains fully supported for backward compatibility.
#812
6218541Thanks @threepointone! - Add custom URL routing withbasePathand server-sent identityCustom URL Routing with
basePathNew
basePathoption bypasses default/agents/{agent}/{name}URL construction, enabling custom routing patterns:Server handles routing manually with
getAgentByName:Server-Sent Identity
Agents now send their identity (
nameandagentclass) to clients on connect:onIdentitycallback - called when server sends identityagent.nameandagent.agentare updated from server (authoritative)Identity State & Ready Promise
identified: boolean- whether identity has been receivedready: Promise<void>- resolves when identity is receivedname,agent, andidentifiedare reactive stateIdentity Change Detection
onIdentityChangecallback - fires when identity differs on reconnectSub-Paths with
pathOptionAppend additional path segments:
Server-Side Identity Control
Disable identity sending for security-sensitive instance names:
#827
e20da53Thanks @threepointone! - Move workflow exports toagents/workflowssubpath for better separation of concerns.#811
f604008Thanks @threepointone! - ### Secure Email Reply RoutingThis release introduces secure email reply routing with HMAC-SHA256 signed headers, preventing unauthorized routing of emails to arbitrary agent instances.
Breaking Changes
Email utilities moved to
agents/emailsubpath: Email-specific resolvers and utilities have been moved to a dedicated subpath for better organization.The following remain in root:
routeAgentEmail,createHeaderBasedEmailResolver(deprecated).createHeaderBasedEmailResolverremoved: This function now throws an error with migration guidance. It was removed because it trusted attacker-controlled email headers for routing.Migration:
createAddressBasedEmailResolver(agentName)createSecureReplyEmailResolver(secret)with signed headersSee https://github.com/cloudflare/agents/blob/main/docs/email.md for details.
EmailSendOptionstype removed: This type was unused and has been removed.New Features
createSecureReplyEmailResolver: A new resolver that verifies HMAC-SHA256 signatures on incoming emails before routing. Signatures include a timestamp and expire after 30 days by default.signAgentHeaders: Helper function to manually sign agent routing headers for use with external email services.replyToEmailsigning: ThereplyToEmailmethod now accepts asecretoption to automatically sign outbound email headers.If an email was routed via
createSecureReplyEmailResolver, callingreplyToEmailwithout a secret will throw an error (pass explicitnullto opt-out).onNoRoutecallback:routeAgentEmailnow accepts anonNoRoutecallback for handling emails that don't match any routing rule.#813
7aebab3Thanks @threepointone! - update dependencies#800
a54edf5Thanks @threepointone! - Update dependencies#818
7c74336Thanks @threepointone! - update dependencies#812
6218541Thanks @threepointone! - # SynchronoussetStatewith validation hooksetState()is now synchronous instead of async. This improves ergonomics and aligns with the expected mental model for state updates.Breaking Changes
setState()returnsvoidinstead ofPromise<void>Existing code that uses
await this.setState(...)will continue to work without changes.onStateUpdate()no longer gates state broadcastsPreviously, if
onStateUpdate()threw an error, the state update would be aborted. Now,onStateUpdate()runs asynchronously viactx.waitUntil()after the state is persisted and broadcast. Errors inonStateUpdate()are routed toonError()but do not prevent the state from being saved or broadcast.If you were using
onStateUpdate()for validation, migrate tovalidateStateChange().New Features
validateStateChange()validation hookA new synchronous hook that runs before state is persisted or broadcast. Use this for validation:
Execution order
validateStateChange(nextState, source)- validation (sync, gating)onStateUpdate(nextState, source)- notifications (async viactx.waitUntil, non-gating)#815
ded8d3eThanks @threepointone! - docs: add OpenAI provider options documentation to scheduleSchemaWhen using
scheduleSchemawith OpenAI models via the AI SDK, users must now passproviderOptions: { openai: { strictJsonSchema: false } }togenerateObject. This is documented in the JSDoc forscheduleSchema.This is required because
@ai-sdk/openainow defaultsstrictJsonSchematotrue, which requires all schema properties to be in therequiredarray. ThescheduleSchemauses optional fields which are not compatible with this strict mode.Updated dependencies [
7aebab3,77be4f8,a54edf5,7c74336,99cbca0]:@cloudflare/[email protected]
Patch Changes
#813
7aebab3Thanks @threepointone! - update dependencies#797
77be4f8Thanks @iTrooz! - refactor(ai-chat): put SSE reply and plaintext reply logic into 2 separate functions#800
a54edf5Thanks @threepointone! - Update dependencies#818
7c74336Thanks @threepointone! - update dependencies#795
99cbca0Thanks @Jerrynh770! - Fix resumable streaming to avoid delivering live chunks before resume ACKUpdated dependencies [
0c3c9bb,0c3c9bb,d1a0c2b,6218541,6218541,6218541,6218541,fd79481,6218541,0c3c9bb,6218541,6218541,e20da53,f604008,7aebab3,a54edf5,7c74336,6218541,ded8d3e]:@cloudflare/[email protected]
Patch Changes
#813
7aebab3Thanks @threepointone! - update dependencies#800
a54edf5Thanks @threepointone! - Update dependencies#818
7c74336Thanks @threepointone! - update dependenciesUpdated dependencies [
0c3c9bb,0c3c9bb,d1a0c2b,6218541,6218541,6218541,6218541,fd79481,6218541,0c3c9bb,6218541,6218541,e20da53,f604008,7aebab3,a54edf5,7c74336,6218541,ded8d3e]:[email protected]
Patch Changes
#800
a54edf5Thanks @threepointone! - Update dependenciesUpdated dependencies [
0c3c9bb,0c3c9bb,d1a0c2b,6218541,6218541,6218541,6218541,fd79481,6218541,0c3c9bb,6218541,6218541,e20da53,f604008,7aebab3,a54edf5,7c74336,6218541,ded8d3e]: