Cloudflare Agents Guide: Durable Workflows and Human Approval

InYourLeague Research · 2026-08-29

Answer in brief

Use AgentWorkflow when a Cloudflare Agent needs long-running, retryable work, durable state synchronization, external-event waits, or human approval. Recovery is step-scoped: operations performed through the workflow step are durable, while progress reports, client broadcasts, and direct Agent RPC calls may repeat after a retry.

Key facts at a glance

Failure modes and verification

FAQ

When should Cloudflare Agents use AgentWorkflow?

Use AgentWorkflow for multi-step work that needs guaranteed delivery, automatic retries, durable recovery, long-running background processing, external-event waits, or human approval. See the official Workflow guide.

Does automatic retry repeat completed step.do() operations?

No. Cloudflare documents completed durable steps as permanent, so they do not execute again after a workflow restart; failed steps can retry with configurable backoff.

Can progress reports or Agent RPC calls run more than once?

Yes. this.reportProgress(), this.broadcastToClients(), and direct calls through this.agent are non-durable and may repeat when a workflow retries.

How does a person approve or reject a paused workflow?

The Workflow pauses through waitForApproval(), and the Agent responds through approveWorkflow() or rejectWorkflow(). The official human-in-the-loop guide provides the documented pattern.

Does cloudflare-agents publish a selectable model ID?

No. The official source does not publish a selectable model ID for this product.

Sources and freshness

• Official source
• Official source
• Last verified: 2026-08-29

Extended guide

Use AgentWorkflow to move failure-sensitive, long-running work out of a Cloudflare Agent and into a durable workflow. Keep real-time interaction in the Agent, and place operations that must survive restarts, retry automatically, or wait for approval inside durable workflow steps.

Verified scope

This entry was verified against Cloudflare’s official documentation on 2026-08-29. AgentWorkflow, imported from agents/workflows, provides bidirectional communication between a Workflow and its originating Agent. Cloudflare Agents retain the long-lived identity, direct user interaction, WebSockets, HTTP streaming, and built-in state database; Workflows provide run-to-completion execution, step-level persistence, automatic retries and recovery, and durable waiting for external events.

The official source does not publish a selectable model ID for this product.

Integration and recovery boundaries

Recommended implementation sequence

1. Extend AgentWorkflow and implement run(event, step). Read the workflow input from event.payload.
2. Put validation, processing, and other retry-sensitive operations inside distinct, consistently named step.do() calls. A successful durable step will not be repeated if later execution fails.
3. Use step.updateAgentState() or step.mergeAgentState() when synchronized Agent state must survive recovery. Reserve this.reportProgress(), this.broadcastToClients(), and direct Agent RPC calls for updates that can safely repeat.
4. For human review, call this.waitForApproval(step, { timeout: ... }). The Agent can resolve the gate through approveWorkflow() or rejectWorkflow() and can then update its pending-approval state.
5. Finish through step.reportComplete() or report failure through step.reportError(). Agents can also query, pause, resume, terminate, or restart workflows and send events with sendWorkflowEvent().

Release checklist

• Every operation that must not repeat is inside a durable step API.
• Every non-durable RPC, progress message, and WebSocket broadcast is safe to receive more than once.
• Agent state changes requiring recovery use step.updateAgentState() or step.mergeAgentState().
• Approval requests have an explicit timeout appropriate to the application.
• The Agent exposes an authorized path to approve or reject the correct workflow ID.
• Later steps depend only on durable outputs or inputs that can be reconstructed.
• External-event waits account for the documented persistence limit.

Key boundary

Workflow recovery does not make every statement in run() durable. The durable boundary is the operation performed through step. Code outside that boundary—including direct Agent RPC calls, progress reporting, and client broadcasts—may run again. Design those effects as repeat-safe, and use the Workflow guide together with the human-in-the-loop guide when defining approval behavior.

Model availability note: The official source does not specify a selectable model ID.