feat: Add Cloudflare Workflows integration for Agents

[threepointone]

Adds 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:

• Agents handle WebSocket connections and quick operations
• Workflows handle long-running tasks, retries, and human-in-the-loop flows

AgentWorkflow Base Class

Extend AgentWorkflow instead of WorkflowEntrypoint to get typed access to the originating Agent:

export class ProcessingWorkflow extends AgentWorkflow<MyAgent, TaskParams> {
  async run(event: AgentWorkflowEvent<TaskParams>, step: AgentWorkflowStep) {
    const params = event.payload;

    // Call Agent methods via RPC
    await this.agent.updateStatus(params.taskId, "processing");

    // Non-durable: progress reporting (lightweight, for frequent updates)
    await this.reportProgress({
      step: "process",
      percent: 0.5,
      message: "Halfway done"
    });
    this.broadcastToClients({ type: "update", taskId: params.taskId });

    // Durable via step: idempotent, won't repeat on retry
    await step.mergeAgentState({ taskProgress: 0.5 });
    await step.reportComplete(result);

    return result;
  }
}

Agent Methods

• runWorkflow(workflowName, params, options?) - Start workflow with optional metadata for querying
• sendWorkflowEvent(workflowName, workflowId, event) - Send events to waiting workflows
• getWorkflow(workflowId) - Get tracked workflow by ID
• getWorkflows(criteria?) - Query by status, workflowName, or metadata
• deleteWorkflow(workflowId) - Delete a workflow tracking record
• deleteWorkflows(criteria?) - Delete workflows by criteria (status, workflowName, metadata, createdBefore)
• approveWorkflow(workflowId, data?) - Approve a waiting workflow
• rejectWorkflow(workflowId, data?) - Reject a waiting workflow

AgentWorkflow Methods

On this (non-durable, lightweight):

• reportProgress(progress) - Report typed progress object to Agent
• broadcastToClients(message) - Broadcast to WebSocket clients
• waitForApproval(step, opts?) - Wait for approval (throws on rejection)

On step (durable, idempotent):

• step.reportComplete(result?) - Report successful completion
• step.reportError(error) - Report an error
• step.sendEvent(event) - Send custom event to Agent
• step.updateAgentState(state) - Replace Agent state (broadcasts to clients)
• step.mergeAgentState(partial) - Merge into Agent state (broadcasts to clients)

Lifecycle Callbacks

Override these methods to handle workflow events (workflowName is first for easy differentiation):

async onWorkflowProgress(workflowName, workflowId, progress) {} // progress is typed object
async onWorkflowComplete(workflowName, workflowId, result?) {}
async onWorkflowError(workflowName, workflowId, error) {}
async onWorkflowEvent(workflowName, workflowId, event) {}

Workflow Tracking

Workflows are automatically tracked in cf_agents_workflows SQLite table:

• Status, timestamps, errors
• Optional metadata field for queryable key-value data
• Params/output NOT stored by default (could be large)

See docs/workflows.md for full documentation.

PR Reviewer Notes

How to Review This PR

Recommended reading order:

1. docs/workflows.md - Start here for the complete picture. Covers:

   • Why integrate Workflows with Agents
   • Quick start guide
   • Full API reference (note the split between this.* and step.* methods)
   • Common patterns (background processing, approval flows, retry logic, state sync)
   • Workflow cleanup strategies and binding migration

2. packages/agents/src/workflow-types.ts - All type definitions:

   • AgentWorkflowEvent<Params> - Type alias for WorkflowEvent<Params> (for consistency)
   • AgentWorkflowStep - Extended WorkflowStep with durable Agent methods
   • AgentWorkflowParams / AgentWorkflowInternalParams - Combined user + internal params
   • WorkflowCallback types (progress, complete, error, event)
   • DefaultProgress - Default typed progress object
   • WorkflowStatus - Derived from Cloudflare's InstanceStatus
   • WorkflowInfo - Parsed workflow tracking record
   • WorkflowQueryCriteria - For querying workflows
   • WaitForApprovalOptions / ApprovalEventPayload - Human-in-the-loop types
   • WorkflowRejectedError - Thrown when workflow is rejected

3. packages/agents/src/workflow.ts - The AgentWorkflow base class:

   • Constructor hook that initializes this.agent before run() executes
   • _wrapStep() - Wraps WorkflowStep with durable Agent methods
   • Non-durable methods on this (lightweight, may repeat on retry):
     • reportProgress() - For frequent progress updates
     • broadcastToClients() - Fire-and-forget WebSocket broadcast
     • waitForApproval() - Human-in-the-loop (throws WorkflowRejectedError on rejection)
     • fetchAgent() - HTTP request to Agent
   • Durable methods on step (idempotent via step.do(), won't repeat on retry):
     • step.reportComplete() - Report completion
     • step.reportError() - Report errors
     • step.sendEvent() - Send custom events
     • step.updateAgentState() - Replace Agent state
     • step.mergeAgentState() - Merge into Agent state

4. packages/agents/src/index.ts - Agent class additions (search for cf_agents_workflows):

   • SQLite table schema and initialization (with workflow_name index)
   • runWorkflow() - Starts workflow with optional agentBinding override
   • getWorkflow() / getWorkflows() - Query tracked workflows by status, name, metadata
   • deleteWorkflow() / deleteWorkflows() - Cleanup tracking records
   • sendWorkflowEvent() - Send events to waiting workflows
   • approveWorkflow() / rejectWorkflow() - Human-in-the-loop convenience methods
   • migrateWorkflowBinding() - Migrate records after renaming bindings
   • onWorkflowCallback() and onWorkflow* lifecycle methods
   • Internal RPC methods: _workflow_handleCallback, _workflow_broadcast, _workflow_updateState (secure workflow-to-agent communication)
   • Orphan detection on startup (_checkOrphanedWorkflows)

5. Tests (in order):

   • packages/agents/src/tests/test-workflow.ts - Example test workflows using new step.* API
   • packages/agents/src/tests/workflow.test.ts - Unit tests for tracking, callbacks, cleanup, and migration
   • packages/agents/src/tests/workflow-integration.test.ts - Integration tests (some skipped due to introspection limitations with durable steps)

6. examples/workflows/ - Demo Vite app showing:

   • Multi-step workflow with progress tracking
   • Human-in-the-loop approval gate
   • Real-time state sync to React UI
   • Demonstrates the this.* vs step.* method split

[changeset-bot]

🦋 Changeset detected

Latest commit: a099119

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
agents	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/agents@799

commit: a099119

[threepointone]

I went through all the claude code review comments and addressed the legit ones.

[deathbyknowledge]

Left a few non blocking questions. This is lit

[mia303]

is this to delete the entire workflow, i.e. https://developers.cloudflare.com/api/resources/workflows/methods/delete/ or specific instances? looks like instances from "errored", "terminated" filter, should be clear

[threepointone]

this is just to wipe out an instance, but we don't have anything to delete the top level Workflow (and never will), so it shouldn't be as confusing

[mia303]

I don't know that it makes sense to call this a "task queue"

[threepointone]

got any reccos for what to call it?

[threepointone]

I'm going to land this, but will carry on the conversation with @mia303 since they're not blocking any functionality.

excited to get this into people's hands, lfg