feat: Add Cloudflare Workflows integration for Agents

[agents-git-bot]

Summary

Syncs documentation for Cloudflare Workflows integration with Agents from cloudflare/agents PR #799.

This PR adds comprehensive documentation for the new AgentWorkflow integration that enables seamless interaction between Cloudflare Agents and Cloudflare Workflows for durable, multi-step background processing.

Changes

New guide: Integrate Cloudflare Workflows with Agents

• Complete integration guide at /agents/guides/cloudflare-workflows-integration/
• Introduction explaining when and why to use Workflows with Agents
• Quick start guide with code examples
• Comprehensive API reference for AgentWorkflow class and Agent methods
• Workflow tracking and lifecycle callback documentation
• Common patterns: background processing, human-in-the-loop, retries, state sync
• Best practices and limitations

Updated API reference: Run Workflows

• Added AgentWorkflow integration section to existing /agents/api-reference/run-workflows/
• Cross-references to comprehensive guide
• Examples showing both basic and advanced integration

Key Features Documented

• AgentWorkflow class - Extended WorkflowEntrypoint with typed Agent access
• Automatic tracking - Workflows tracked in Agent SQLite database
• Progress reporting - Custom typed progress updates
• Lifecycle callbacks - onWorkflowProgress, onWorkflowComplete, onWorkflowError
• Bidirectional communication - Agent ↔ Workflow via RPC, HTTP, and events
• State synchronization - Update Agent state from workflows (broadcasts to clients)
• Human-in-the-loop - Built-in approval flow support

Related

Source PR: cloudflare/agents#799

🤖 Generated with Claude Code

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
/src/content/changelog/	@cloudflare/pm-changelogs, @cloudflare/pcx-technical-writing

[github-actions]

Preview URL: https://7d26e18f.preview.developers.cloudflare.com
Preview Branch URL: https://sync-docs-pr-799.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/changelog/2026-01-28-agents-workflows-integration/	https://sync-docs-pr-799.preview.developers.cloudflare.com/changelog/2026-01-28-agents-workflows-integration/

[agents-git-bot]

Updated documentation with comprehensive Workflows integration guide.

This update completely rewrites the run-workflows.mdx file to document the new Workflows integration features from cloudflare/agents PR #799.

Key additions:

• Complete API reference for AgentWorkflow base class
• Documentation for 10+ new Agent methods for workflow management
• 5 detailed pattern examples (background processing, approvals, retries, state sync, custom types)
• Database schema for workflow tracking
• Best practices for cleanup and maintenance

All content follows Cloudflare style guidelines and uses appropriate components (TypeScriptExample, WranglerConfig, Type).

[agents-git-bot]

Updated Documentation

This PR has been updated with comprehensive Workflows integration documentation that includes:

New Content Added

• AgentWorkflow Base Class: Complete API reference with type parameters, properties, and methods
• Automatic Workflow Tracking: Documentation for the cf_agents_workflows SQLite table
• Lifecycle Callbacks: Full coverage of onWorkflowProgress, onWorkflowComplete, onWorkflowError, and onWorkflowEvent
• Approval Methods: Human-in-the-loop patterns with approveWorkflow() and rejectWorkflow()
• State Synchronization: updateAgentState() and mergeAgentState() for broadcasting to clients
• Comprehensive Patterns: Background processing, approval flows, retry logic, custom progress types, and state sync
• Best Practices: Cleanup strategies, binding migration, and workflow management
• API Reference: Complete documentation for all Agent workflow methods

Documentation Structure

The updated documentation follows the Diátaxis framework:

• Quick Start: Step-by-step guide to get started quickly
• API Reference: Complete technical documentation for all classes and methods
• Patterns: Real-world usage examples for common scenarios
• Best Practices: Guidance on managing workflows effectively

All content has been adapted to follow Cloudflare docs style conventions, including proper use of TypeScriptExample and WranglerConfig components.

The documentation now provides developers with everything they need to integrate Cloudflare Workflows with Agents for durable, multi-step background processing.

[github-actions]

CI run failed: build logs

[elithrar]

---
title: Kick off long-running Workflows from your Agents
description: The Agents SDK now has first-class support for Cloudflare Workflows, enabling durable multi-step background processing with automatic tracking and bidirectional communication.
products:
  - agents
  - workflows
date: 2026-01-28
---

import { TypeScriptExample } from "~/components";

The Agents SDK now has first-class support for [Cloudflare Workflows](/workflows/), allowing you to kick off durable, long-running async tasks from your Agent. Track workflow progress, sync state back to your Agent, and implement human-in-the-loop approval flows—all with automatic tracking in SQLite.

Use the new `AgentWorkflow` class to define workflows with typed access to your Agent:

<TypeScriptExample>

```ts
import { AgentWorkflow } from "agents";
import type { AgentWorkflowEvent, AgentWorkflowStep } from "agents";

export class ProcessingWorkflow extends AgentWorkflow<MyAgent, TaskParams> {
  async run(event: AgentWorkflowEvent<TaskParams>, step: AgentWorkflowStep) {
    // Report progress to Agent
    await this.reportProgress({ step: "process", percent: 0.5 });

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

    const result = await step.do("process", async () => {
      return processData(event.payload.data);
    });

    await step.reportComplete(result);
    return result;
  }
}
```

</TypeScriptExample>

Start workflows from your Agent with `runWorkflow()` and handle lifecycle events:

<TypeScriptExample>

```ts
export class MyAgent extends Agent {
  async startTask(taskId: string, data: string) {
    // Automatically tracked in Agent database
    const workflowId = await this.runWorkflow("PROCESSING_WORKFLOW", { taskId, data });
    return { workflowId };
  }

  async onWorkflowProgress(workflowName: string, workflowId: string, progress: unknown) {
    this.broadcast(JSON.stringify({ type: "progress", progress }));
  }

  async onWorkflowComplete(workflowName: string, workflowId: string, result?: unknown) {
    console.log(`Workflow ${workflowId} completed`);
  }
}
```

</TypeScriptExample>

Key capabilities:
- **Automatic tracking** in the Agent SQLite database
- **Progress reporting** with typed progress objects
- **Bidirectional communication** between Agents and Workflows via RPC
- **State synchronization** from Workflows back to Agents (broadcasts to clients)
- **Human-in-the-loop** with `waitForApproval()` and `approveWorkflow()`/`rejectWorkflow()`

For the complete API reference and patterns, see [Integrate with Cloudflare Workflows](/agents/guides/workflows-integration/).