Reference

Workflows


A workflow is the function that decides what happens, in what order. The engine journals each step it takes, and every time the workflow resumes (after a task finishes, a timer fires or a worker restarts) the SDK replays the workflow code against that journal. Steps that already happened return their recorded results instead of running again.

That replay is why workflow code must be deterministic: given the same journal, it must make the same calls in the same order. Do I/O in tasks, and use ctx.time, ctx.random and ctx.sleep() instead of the clock, random and asyncio.sleep.


Defining a workflow

Decorate an async function whose first parameter is the WorkflowContext:

1
@workflow(
2
name="order", # required: the workflow type clients start
3
version="1.0", # optional label, default "1.0"
4
description="Charge and ship an order",
5
)
6
async def order(ctx: WorkflowContext, order_id: str, amount: int) -> str:
7
payment = await ctx.execute_task(charge, order_id=order_id, amount=amount)
8
shipped = await ctx.execute_task(ship, order_id=order_id)
9
return f"{payment['charge_id']}: {shipped}"

name is required, and is the type clients start. version is a label recorded on the execution for logs and metrics (see Changing workflow code); description is free text.

A class with an async def run(self, ctx, ...) method works too, and keeps its type under the decorator:

1
@workflow(name="order-v2")
2
class OrderWorkflow:
3
async def run(self, ctx: WorkflowContext, order_id: str, amount: int) -> str:
4
payment = await ctx.execute_task(charge, order_id=order_id, amount=amount)
5
return str(payment["charge_id"])

@workflow also accepts cron_schedule=, but that value is only kept in the workflow's metadata: the worker doesn't send it to the engine. See cron schedules for running a workflow on a schedule.


Inputs and results

A workflow's input arrives the way it was sent. A dict is spread into keyword arguments, any other single value is passed as one positional argument, and no input passes nothing:

1
@workflow(name="greet")
2
async def greet(ctx: WorkflowContext, name: str, greeting: str = "Hello") -> str:
3
return f"{greeting}, {name}!"
1
# A dict is spread into keyword arguments: greet(ctx, name="Ada").
2
await client.start_workflow("greet", task_queue="default", args=({"name": "Ada"},))
3
4
# Any other single value is passed as one positional argument.
5
await client.start_workflow("greet", task_queue="default", args=("Ada",))

Several values in args arrive as one list argument, not as separate arguments, so send a dict when the workflow takes more than one parameter.

Inputs and results travel as JSON: return dicts, lists, strings, numbers, booleans or None from a workflow.


Running tasks

Pass the task function itself, not its name, and its arguments as keyword arguments:

1
payment = await ctx.execute_task(charge, order_id=order_id, amount=amount)

The first time the workflow reaches this line, the task is scheduled and the workflow suspends. When the task completes, the workflow is replayed and the call returns the task's result from the journal. Results travel as JSON. A function task (not a @tasks method) whose return annotation is a dataclass hands the workflow that dataclass, rebuilt from the JSON; otherwise the workflow gets the decoded JSON value, such as a dict.

Per-call options

The retry policy, timeout and heartbeat timeout default to what @task declared; pass them to override for one call. queue_timeout bounds how long the task may wait for a worker to pick it up, separately from how long it may run:

1
@workflow(name="charge-with-overrides")
2
async def charge_with_overrides(ctx: WorkflowContext, order_id: str) -> dict:
3
result: dict = await ctx.execute_task(
4
charge,
5
order_id=order_id,
6
amount=4200,
7
# Each of these overrides what @task declared, for this call only.
8
retry_policy=RetryPolicy(max_attempts=5, initial_interval=timedelta(seconds=2)),
9
timeout=timedelta(seconds=60),
10
heartbeat_timeout=timedelta(seconds=15),
11
queue_timeout=timedelta(minutes=5),
12
)
13
return result

When a task fails

When a task fails for good (its retries are used up, or the error is non-retryable), execute_task raises TaskError in the workflow. Catch it to take another path; leave it uncaught and the workflow fails:

1
@workflow(name="reserve-or-report")
2
async def reserve_or_report(ctx: WorkflowContext, order_id: str) -> str:
3
try:
4
reservation = await ctx.execute_task(reserve, order_id=order_id)
5
except TaskError as err:
6
# Raised once the task has failed for good: retries are used up, or
7
# the error was non-retryable.
8
return f"could not reserve {order_id}: {err.message}"
9
return str(reservation["reservation_id"])

except Exception in workflow code is safe: the signal the SDK uses to suspend a workflow derives from BaseException, so it passes through. Don't put workflow steps in a finally block, though: finally also runs every time the workflow suspends.

Running tasks in parallel

await suspends at the first task whose result isn't in the journal yet, so a loop of await ctx.execute_task(...) runs its tasks one after another. To run them at the same time, schedule them together with asyncio.gather:

1
@workflow(name="process-batch")
2
async def process_batch(ctx: WorkflowContext, item_ids: list[str]) -> list[str]:
3
# All the tasks are scheduled at once; the workflow resumes when they finish.
4
results = await asyncio.gather(
5
*(ctx.execute_task(process_item, item_id=item_id) for item_id in item_ids)
6
)
7
return list(results)

Inline steps

ctx.execute() runs a function inside the workflow worker once and journals its result. On replay the function doesn't run again; the call returns the journaled value. It suits a quick, read-only lookup that doesn't need its own retry policy or worker:

1
@workflow(name="convert")
2
async def convert(ctx: WorkflowContext, amount: int, currency: str) -> float:
3
# Runs in the workflow worker once; replays return the journaled value.
4
rate = await ctx.execute("exchange-rate", lambda: lookup_exchange_rate(currency))
5
return amount * rate

The function takes no arguments and its result must be JSON-serializable. A step that raises is not journaled, so it runs again on the next activation. Anything that needs retries, a timeout or a different worker belongs in a task.


Timers

ctx.sleep() starts a durable timer. It takes a timedelta; a bare number is rejected because its unit would be ambiguous:

1
@workflow(name="trial")
2
async def trial(ctx: WorkflowContext, email: str) -> None:
3
# A durable timer: the engine keeps it, so no worker waits and a restart
4
# does not reset it.
5
await ctx.sleep(timedelta(days=13))
6
await ctx.execute_task(send_reminder, email=email)
7
8
# The same, with an id you choose instead of a generated one.
9
await ctx.sleep_with_id("trial-end", timedelta(days=1))

No worker is busy while a timer runs, so a workflow can wait for days or months.


Child workflows

execute_child_workflow starts another workflow by its type name and waits for its result. A failed, canceled or terminated child raises WorkflowError in the parent:

1
@workflow(name="print-label")
2
async def print_label(ctx: WorkflowContext, order_id: str) -> str:
3
return f"label-{order_id}"
4
5
6
@workflow(name="ship-order")
7
async def ship_order(ctx: WorkflowContext, order_id: str) -> str:
8
# Starts the child and waits for its result.
9
label = await ctx.execute_child_workflow("print-label", args=(order_id,))
10
return f"{order_id} shipped with {label}"

start_child_workflow returns a handle without waiting, so several children can run at once:

1
@workflow(name="ship-orders")
2
async def ship_orders(ctx: WorkflowContext, order_ids: list[str]) -> list[str]:
3
# start_child_workflow does not wait, so every child starts at once.
4
handles = [
5
await ctx.start_child_workflow(
6
"print-label",
7
workflow_id=f"label-{order_id}", # optional; generated if omitted
8
args=(order_id,),
9
)
10
for order_id in order_ids
11
]
12
labels: list[str] = []
13
for handle in handles:
14
labels.append(await handle.result())
15
return labels

Children run on the parent's task queue unless you pass task_queue=. Without a workflow_id the SDK derives one from the step's position, which is the same on every replay; give one when you want to address the child yourself. A child's args follow the same rules as a workflow's input.

A handle can also send the child an event or cancel it. Both are journaled, so a replay doesn't repeat them:

1
@workflow(name="supervise")
2
async def supervise(ctx: WorkflowContext, job_id: str) -> None:
3
child = await ctx.start_child_workflow("run-job", workflow_id=f"job-{job_id}", args=(job_id,))
4
await child.send_event("priority", {"level": "high"})
5
# Or stop it: waiting for its result then raises WorkflowError.
6
await child.cancel()

Events

An event is a named message sent to a running workflow. wait_for_event waits until one with that name arrives and returns its payload:

1
@workflow(name="approval")
2
async def approval(ctx: WorkflowContext, request_id: str) -> str:
3
decision = await ctx.wait_for_event("decision")
4
return "approved" if decision["approved"] else "rejected"

wait_for_event_with_timeout takes a timedelta and raises TimeoutError if the deadline comes first. The deadline is a durable timer, so it holds while no worker is running the workflow:

1
@workflow(name="approval-with-deadline")
2
async def approval_with_deadline(ctx: WorkflowContext, request_id: str) -> str:
3
try:
4
decision = await ctx.wait_for_event_with_timeout("decision", timedelta(days=3))
5
except TimeoutError:
6
return "expired"
7
return "approved" if decision["approved"] else "rejected"

Events that arrive before the workflow waits for them are kept, and each wait takes the oldest. Send one from a client:

1
handle = await client.get_workflow("approval-42")
2
await handle.send_event("decision", {"approved": True})

Or from another workflow, journaled so a replay doesn't send it again:

1
@workflow(name="notify-order")
2
async def notify_order(ctx: WorkflowContext, order_id: str) -> None:
3
# Journaled: a replay does not send it again.
4
await ctx.send_event("order-456", "payment-received", {"amount": 100})

State, queries and updates

ctx.set_state() and ctx.get_state() keep key-value state in the workflow's memory. It isn't stored separately: replay rebuilds it by running the workflow code again. Outside the workflow it can only be read through a query.

Queries

A query handler returns a value computed from the workflow's state, without changing it. Register one from the workflow; it receives the context as its first argument:

1
@workflow(name="import-items")
2
async def import_items(ctx: WorkflowContext, item_ids: list[str]) -> int:
3
ctx.set_state("done", 0)
4
ctx.register_query_handler("progress", lambda qctx: {"done": qctx.get_state("done", 0)})
5
6
for count, item_id in enumerate(item_ids, start=1):
7
await ctx.execute_task(process_item, item_id=item_id)
8
ctx.set_state("done", count)
9
return len(item_ids)

The @query decorator registers a handler under one name for every workflow the worker runs:

1
# Registered for every workflow the worker runs, under this name.
2
@query(name="status")
3
def status(ctx: WorkflowContext) -> Any:
4
return ctx.get_state("status", "unknown")

Queries are answered by a worker running the workflow, so they work only while the run is open and a worker for its queue is up.

Updates

An update handler receives arguments from a client and returns a result to it:

1
@update(name="set-priority")
2
async def set_priority(ctx: WorkflowContext, level: str) -> dict:
3
previous = ctx.get_state("priority", "normal")
4
ctx.set_state("priority", level)
5
return {"previous": previous, "now": level}
1
handle = await client.get_workflow("import-2026-10-07")
2
progress = await handle.query("progress")
3
print(progress["done"])
4
5
# A dict argument reaches the handler as keyword arguments.
6
changed = await handle.update("set-priority", {"level": "high"})
7
print(changed)

Time and randomness

ctx.time and ctx.random give the same answers on every replay:

1
@workflow(name="invoice")
2
async def invoice(ctx: WorkflowContext, customer: str) -> dict:
3
number = ctx.random.uuid() # a str, the same on every replay
4
reviewer = ctx.random.choice(["ana", "kofi", "lee"])
5
issued_at = ctx.time.now() # when the engine journaled the start
6
7
await ctx.sleep(timedelta(days=30))
8
# ctx.time has moved on to when the timer fired.
9
if ctx.time.elapsed() >= timedelta(days=30):
10
await ctx.execute_task(send_reminder, email=f"{customer}@example.com")
11
12
if not ctx.replaying:
13
log.info("invoice %s sent for review to %s", number, reviewer)
14
15
return {"number": number, "issued_at": issued_at.isoformat(), "reviewer": reviewer}
  • ctx.time.now() is not the wall clock. It starts at the moment the engine journaled the workflow's start, and moves forward each time the workflow receives something it waited for (a task result, a fired timer, a child's outcome or an event) to when the engine journaled that. It doesn't move while the code runs between those points. ctx.time.started_at() never moves, and ctx.time.elapsed() is the difference.
  • ctx.random is seeded from the run's ids and offers random(), randint(a, b), choice(seq), shuffle(seq), sample(population, k) and uuid() (a string).
  • ctx.replaying is True while the code is catching up with the journal. Use it to keep logs from repeating on every replay, never to change what the workflow does.

Changing workflow code

On replay the SDK checks the code against the journal. A run whose code no longer matches what it recorded is held: the activation is not applied, the error is reported, and the run is retried with backoff. Nothing is lost, and a run that was held because of a bad deploy continues once the code it needs is running again.

What is caught:

  • code that no longer reaches a step the journal recorded, for example a task call that was removed; and
  • code that issues different work at a recorded position, for example a different task where another used to be.

What is not caught (tracked in sdk-core#14):

  • reordering steps of different kinds, such as moving a timer before a task; and
  • changing a timer's duration.

Step ids come from each step's position in the code and its name (charge_1, timer_2, child_3), so the safe changes are ones that leave existing runs' recorded steps where they were. To change a workflow with runs in flight:

  • Give each worker a version_id for the code it runs. The engine binds an execution to the version of the worker that first claims it, so it keeps replaying against that code.
  • Or put the new logic under a new workflow name and start new runs there, leaving old runs on the old code.
  • Or reset affected runs to a point before the change.

ctx.version returns the version= label from @workflow. It is not a replay mechanism: don't branch on it.


Restart with fresh history

A workflow that loops for a long time accumulates a long journal, which every replay reads. ctx.restart_fresh() ends the current run and starts a new one with an empty journal and the input you pass; nothing after the call runs:

1
@workflow(name="sync-catalog")
2
async def sync_catalog(ctx: WorkflowContext, cursor: str | None = None) -> int:
3
page = await ctx.execute_task(fetch_page, cursor=cursor)
4
for item in page["items"]:
5
await ctx.execute_task(process_item, item_id=item["id"])
6
7
if page["next_cursor"]:
8
# Ends this run and starts a new one, with an empty journal, whose
9
# input is the next cursor. Nothing after this line runs.
10
ctx.restart_fresh(page["next_cursor"])
11
12
return len(page["items"])

Pass workflow_type= or task_queue= to continue as a different workflow or on another queue.


Reset

Resetting rewinds a run to an event in its journal and runs it on from there with fresh decisions. It's done from a client:

1
handle = await client.get_workflow("order-12345")
2
3
# Keep journal events 1 to 5, discard the rest, and run on from there.
4
new_execution_id = await handle.reset(target_event_id=5, reason="bad deploy")
5
print(f"new execution: {new_execution_id}")

Find the event id with orcher workflow history:

1
orcher workflow history order-12345

Workflow metadata

1
@workflow(name="describe-self", version="2.1")
2
async def describe_self(ctx: WorkflowContext) -> dict:
3
info = ctx.info
4
return {
5
"workflow_id": info.workflow_id,
6
"run_id": info.run_id,
7
"type": info.workflow_type,
8
"queue": info.task_queue,
9
"namespace": info.namespace,
10
"version": ctx.version, # the label from @workflow, for logs and metrics
11
}

ctx.info also has attempt and started_at. ctx.execution returns the workflow_id and run_id as a WorkflowExecution.


WorkflowContext reference

Method or propertyDescription
await ctx.execute_task(fn, **kwargs)Run a task and return its result; raises TaskError if it fails for good
await ctx.execute(name, fn)Run a no-argument function once and journal its result
await ctx.sleep(timedelta)Durable timer
await ctx.sleep_with_id(id, timedelta)Durable timer with an id you choose
await ctx.execute_child_workflow(type, *, workflow_id=None, args=(), task_queue=None)Start a child workflow and return its result
await ctx.start_child_workflow(type, *, workflow_id=None, args=(), task_queue=None)Start a child workflow and return a ChildWorkflowHandle (result(), send_event(), cancel())
await ctx.cancel_child(workflow_id)Cancel a child workflow
await ctx.wait_for_event(name)Wait for an event and return its payload
await ctx.wait_for_event_with_timeout(name, timedelta)The same, raising TimeoutError at the deadline
await ctx.send_event(workflow_id, name, data=None)Send an event to another workflow
ctx.set_state(key, value) / ctx.get_state(key, default=None)In-memory workflow state
ctx.register_query_handler(name, fn)Answer a query; fn(ctx, ...)
ctx.register_update_handler(name, fn)Accept an update; fn(ctx, ...)
await ctx.create_session(options=None)Pin tasks to one worker; see Sessions
ctx.restart_fresh(input=None, *, workflow_type=None, task_queue=None)End this run and start a new one with an empty journal
ctx.timeReplay-safe clock: now(), started_at(), elapsed()
ctx.randomReplay-safe random numbers
ctx.replayingWhether the code is catching up with the journal
ctx.info / ctx.executionWorkflowInfo / WorkflowExecution
ctx.versionThe @workflow version label

Next steps

  • Tasks: retries, heartbeats and cancellation
  • Client: start workflows and read their results
  • Patterns: compensation, fan-out and approvals