导航|地址|刷新
Run Workflows

Skip to contentDocumentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/agents/llms.txt
Use this file to discover all available pages before exploring further.



DocsDirectoryAPISDKsChangelog

Search

Log in






Agents

/




Overview


Getting started


Quick start

Add to existing project

Testing your Agents






Concepts


What are agents?

Conversation state and memory

Tools

Calling LLMs

Using Agents with Workflows


Agentic patterns


Overview

Human-in-the-loop patterns

Long-running agents










Communication channels



Chat


Chat agents

Autonomous responses

Client SDK





Voice

Email

Slack


Webhooks


Overview

Push notifications










Tools


Sandbox

MCP

Browser

AI Search


Agentic Payments


Overview

Charge for HTTP content


x402


Overview

Charge for HTTP content

Charge for MCP tools

Pay from Agents SDK

Pay from coding tools





MPP (Machine Payments Protocol)






Code Mode


Overview

Create a durable Code Mode runtime

AI SDK integration

Use Code Mode with TanStack AI

Browser-owned tools

MCP

OpenAPI

How Code Mode works

Code Mode API reference










Harnesses


Overview


Think


Overview

Getting started

Configuration

Tools

Actions

Lifecycle hooks

Client tools

Messengers

Channels

Scheduled tasks

Workflows

Sub-agent RPC and programmatic turns

Programmatic submissions

Durable recovery










Runtime


Agents API


Lifecycle


Agent class internals

Callable methods

Store and sync state

Sessions

getCurrentAgent()






Communication


Routing

WebSockets

HTTP and Server-Sent Events

Chat SDK

Protocol messages

Readonly connections






Execution


Sub-agents

Schedule tasks

Durable execution with fibers

Queue tasks

Retries

Run Workflows

Agents as tools

Agent Skills






Operations


Configuration

Cross-domain authentication

Using AI Models

Observability










Examples


Chat agent

Slack agent

Voice agent

Browser agent

Email agent






Model Context Protocol (MCP)


Overview


APIs


MCP handler APIs

McpAgent

McpClient






Protocol


Tools

Authorization

Transport

MCP governance






Guides


Build MCP client

Build a Remote MCP server

Test a Remote MCP Server

Securing MCP servers

Connect to an MCP server

Handle OAuth with MCP servers

Migrate to MCP SDK v2

Build a single-tool Code Mode MCP server

Build a search and execute MCP server






Cloudflare


MCP server portals ↗


Cloudflare's own MCP servers


Overview

Cloudflare Community MCP Server









Code Mode MCP server patterns






Platform


Limits






Agent resources


Agent setup ↗

Cloudflare Skills ↗

Code Mode MCP Server ↗

Domain-specific MCP Servers ↗MCP

Agents llms.txt ↗

Agents llms-full.txt ↗

Cloudflare Docs llms.txt ↗

Cloudflare Docs llms-full.txt ↗













Home

/Agents

/…
Runtime


/Execution

/Run Workflows



Run Workflows


Last updated Jun 26, 2026|Copy as Markdown|View as Markdown|Agent setup

OverviewQuick start 1. Define a Workflow 2. Start a Workflow from an Agent 3. Configure WranglerAgentWorkflow class Type parameters Properties Instance methods (non-durable) Step methods (durable) DefaultProgress typeAgent workflow methods runWorkflow(workflowName, params, options?) sendWorkflowEvent(workflowName, instanceId, event) getWorkflowStatus(workflowName, instanceId) getWorkflow(instanceId) getWorkflows(criteria?) deleteWorkflow(instanceId) deleteWorkflows(criteria?) terminateWorkflow(instanceId) pauseWorkflow(instanceId) resumeWorkflow(instanceId) restartWorkflow(instanceId, options?) approveWorkflow(instanceId, options?) rejectWorkflow(instanceId, options?) migrateWorkflowBinding(oldName, newName)Lifecycle callbacksWorkflow tracking Status valuesExamples Human-in-the-loop approval Retry with backoff State synchronization Custom progress types Cleanup strategyBidirectional communication Workflow to Agent Agent to WorkflowBest practicesLimitationsRelated resources




Integrate Cloudflare Workflows with Agents for durable, multi-step background processing while Agents handle real-time communication.


Agents vs. Workflows


Agents excel at real-time communication and state management. Workflows excel at durable execution with automatic retries, failure recovery, and waiting for external events.

Use Agents alone for chat, messaging, and quick API calls. Use Agent + Workflow for long-running tasks (over 30 seconds), multi-step pipelines, and human approval flows.




Quick start



1. Define a Workflow


Extend AgentWorkflow for typed access to the originating Agent:






import { AgentWorkflow } from "agents/workflows";export class ProcessingWorkflow extends AgentWorkflow { async run(event, step) { const params = event.payload; const result = await step.do("process-data", async () => { return processData(params.data); }); // Non-durable: progress reporting (may repeat on retry) await this.reportProgress({ step: "process", status: "complete", percent: 0.5, }); // Broadcast to connected WebSocket clients this.broadcastToClients({ type: "update", taskId: params.taskId }); await step.do("save-results", async () => { // Call Agent methods via RPC await this.agent.saveResult(params.taskId, result); }); // Durable: idempotent, won't repeat on retry await step.reportComplete(result); return result; }}

import { AgentWorkflow } from "agents/workflows";import type { AgentWorkflowEvent, AgentWorkflowStep } from "agents/workflows";import type { MyAgent } from "./agent";type TaskParams = { taskId: string; data: string };export class ProcessingWorkflow extends AgentWorkflow<MyAgent, TaskParams> { async run(event: AgentWorkflowEvent<TaskParams>, step: AgentWorkflowStep) { const params = event.payload; const result = await step.do("process-data", async () => { return processData(params.data); }); // Non-durable: progress reporting (may repeat on retry) await this.reportProgress({ step: "process", status: "complete", percent: 0.5, }); // Broadcast to connected WebSocket clients this.broadcastToClients({ type: "update", taskId: params.taskId }); await step.do("save-results", async () => { // Call Agent methods via RPC await this.agent.saveResult(params.taskId, result); }); // Durable: idempotent, won't repeat on retry await step.reportComplete(result); return result; }}





2. Start a Workflow from an Agent


Use runWorkflow() to start and track workflows:






import { Agent } from "agents";export class MyAgent extends Agent { async startTask(taskId, data) { const instanceId = await this.runWorkflow("PROCESSING_WORKFLOW", { taskId, data, }); return { instanceId }; } async onWorkflowProgress(workflowName, instanceId, progress) { this.broadcast(JSON.stringify({ type: "workflow-progress", progress })); } async onWorkflowComplete(workflowName, instanceId, result) { console.log(`Workflow completed:`, result); } async saveResult(taskId, result) { this .sql`INSERT INTO results (task_id, data) VALUES (${taskId}, ${JSON.stringify(result)})`; }}

import { Agent } from "agents";export class MyAgent extends Agent { async startTask(taskId: string, data: string) { const instanceId = await this.runWorkflow("PROCESSING_WORKFLOW", { taskId, data, }); return { instanceId }; } async onWorkflowProgress( workflowName: string, instanceId: string, progress: unknown, ) { this.broadcast(JSON.stringify({ type: "workflow-progress", progress })); } async onWorkflowComplete( workflowName: string, instanceId: string, result?: unknown, ) { console.log(`Workflow completed:`, result); } async saveResult(taskId: string, result: unknown) { this .sql`INSERT INTO results (task_id, data) VALUES (${taskId}, ${JSON.stringify(result)})`; }}





3. Configure Wrangler






{ "name": "my-app", "main": "src/index.ts", // Set this to today's date "compatibility_date": "2026-07-31", "durable_objects": { "bindings": [{ "name": "MY_AGENT", "class_name": "MyAgent" }], }, "workflows": [ { "name": "processing-workflow", "binding": "PROCESSING_WORKFLOW", "class_name": "ProcessingWorkflow", }, ], "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }],}

name = "my-app"main = "src/index.ts"# Set this to today's datecompatibility_date = "2026-07-31"[[durable_objects.bindings]]name = "MY_AGENT"class_name = "MyAgent"[[workflows]]name = "processing-workflow"binding = "PROCESSING_WORKFLOW"class_name = "ProcessingWorkflow"[[migrations]]tag = "v1"new_sqlite_classes = [ "MyAgent" ]




AgentWorkflow class


Base class for Workflows that integrate with Agents.


Type parameters

Parameter	Description
AgentType	The Agent class type for typed RPC
Params	Parameters passed to the workflow
ProgressType	Type for progress reporting (defaults to DefaultProgress)
Env	Environment type (defaults to Cloudflare.Env)

Properties

Property	Type	Description
agent	Stub	Typed stub for calling Agent methods. For workflows started from a sub-agent, this is an RPC-only stub back to the originating facet; use sub-agent routing for HTTP or WebSocket fetch() traffic
instanceId	string	The workflow instance ID
workflowName	string	The workflow binding name
env	Env	Environment bindings

Instance methods (non-durable)


These methods may repeat on retry. Use for lightweight, frequent updates.


reportProgress(progress)


Report progress to the Agent. Triggers onWorkflowProgress callback.






await this.reportProgress({ step: "processing", status: "running", percent: 0.5,});

await this.reportProgress({ step: "processing", status: "running", percent: 0.5,});





broadcastToClients(message)


Broadcast a message to all WebSocket clients connected to the Agent.






this.broadcastToClients({ type: "update", data: result });

this.broadcastToClients({ type: "update", data: result });





waitForApproval(step, options?)


Wait for an approval event. Throws WorkflowRejectedError if rejected.






const approval = await this.waitForApproval(step, { timeout: "7 days",});

const approval = await this.waitForApproval<{ approvedBy: string }>(step, { timeout: "7 days",});





Step methods (durable)


These methods are idempotent and will not repeat on retry. Use for state changes that must persist.

Method	Description
step.reportComplete(result?)	Report successful completion
step.reportError(error)	Report an error
step.sendEvent(event)	Send a custom event to the Agent
step.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

DefaultProgress type

type DefaultProgress = { step?: string; status?: "pending" | "running" | "complete" | "error"; message?: string; percent?: number; [key: string]: unknown;};

Agent workflow methods


Methods available on the Agent class for Workflow management.


runWorkflow(workflowName, params, options?)


Start a workflow instance and track it in the Agent database.

Parameters:

Parameter	Type	Description
workflowName	string	Workflow binding name from env
params	object	Parameters to pass to the workflow
options.id	string	Custom workflow ID (auto-generated if not provided)
options.metadata	object	Metadata stored for querying (not passed to workflow)
options.agentBinding	string	Agent binding name (auto-detected if not provided). When called from a sub-agent, this is the root Agent binding name

Returns:Promise<string> - Workflow instance ID






const instanceId = await this.runWorkflow( "MY_WORKFLOW", { taskId: "123" }, { metadata: { userId: "user-456", priority: "high" }, },);

const instanceId = await this.runWorkflow( "MY_WORKFLOW", { taskId: "123" }, { metadata: { userId: "user-456", priority: "high" }, },);





Starting workflows from sub-agents


Sub-agents can call this.runWorkflow() directly. The workflow is tracked in the originating sub-agent's SQLite database, and this.agent inside AgentWorkflow routes back to that same sub-agent for RPC calls, callbacks, state updates, and broadcasts.

Parent agents do not automatically list or control workflows that a sub-agent starts. SubAgentStub<T> only exposes user-defined methods, not inherited Agent methods such as approveWorkflow() or getWorkflow(). To control a child-started workflow from the parent, define small wrapper methods on the child and call those wrappers through the sub-agent stub.






export class ParentAgent extends Agent { async startChildWorkflow(childName, task) { const child = await this.subAgent(ChildAgent, childName); return child.startWorkflow(task); } async approveChildWorkflow(childName, workflowId) { const child = await this.subAgent(ChildAgent, childName); return child.approveChildWorkflow(workflowId); }}export class ChildAgent extends Agent { async startWorkflow(task) { return this.runWorkflow("CHILD_WORKFLOW", { task }); } async approveChildWorkflow(workflowId) { return this.approveWorkflow(workflowId); } async getChildWorkflow(workflowId) { return this.getWorkflow(workflowId); }}

export class ParentAgent extends Agent { async startChildWorkflow(childName: string, task: string) { const child = await this.subAgent(ChildAgent, childName); return child.startWorkflow(task); } async approveChildWorkflow(childName: string, workflowId: string) { const child = await this.subAgent(ChildAgent, childName); return child.approveChildWorkflow(workflowId); }}export class ChildAgent extends Agent { async startWorkflow(task: string) { return this.runWorkflow("CHILD_WORKFLOW", { task }); } async approveChildWorkflow(workflowId: string) { return this.approveWorkflow(workflowId); } async getChildWorkflow(workflowId: string) { return this.getWorkflow(workflowId); }}




For sub-agent origins, AgentWorkflow.agent is an RPC-only stub. Use it to call Agent methods, but use routeSubAgentRequest() or the /agents/{parent}/{name}/sub/{child}/{name} URL shape for external HTTP or WebSocket routing instead of
…(内容过长已截断)

------
导航页 打开网址