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 start3 version="1.0", # optional label, default "1.0"4 description="Charge and ship an order",5)6async 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")2class 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")2async 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").2await client.start_workflow("greet", task_queue="default", args=({"name": "Ada"},))34# Any other single value is passed as one positional argument.5await 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:
1payment = 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")2async 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 resultWhen 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")2async 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, or7 # 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")2async 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")2async 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 * rateThe 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")2async def trial(ctx: WorkflowContext, email: str) -> None:3 # A durable timer: the engine keeps it, so no worker waits and a restart4 # does not reset it.5 await ctx.sleep(timedelta(days=13))6 await ctx.execute_task(send_reminder, email=email)78 # 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")2async def print_label(ctx: WorkflowContext, order_id: str) -> str:3 return f"label-{order_id}"456@workflow(name="ship-order")7async 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")2async 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 omitted8 args=(order_id,),9 )10 for order_id in order_ids11 ]12 labels: list[str] = []13 for handle in handles:14 labels.append(await handle.result())15 return labelsChildren 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")2async 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")2async 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")2async 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:
1handle = await client.get_workflow("approval-42")2await handle.send_event("decision", {"approved": True})Or from another workflow, journaled so a replay doesn't send it again:
1@workflow(name="notify-order")2async 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")2async 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)})56 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")3def 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")2async 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}1handle = await client.get_workflow("import-2026-10-07")2progress = await handle.query("progress")3print(progress["done"])45# A dict argument reaches the handler as keyword arguments.6changed = await handle.update("set-priority", {"level": "high"})7print(changed)State an update handler sets lasts only until the workflow's next activation, which rebuilds state by replaying the workflow code. To change what a workflow does, send it an event and have the workflow act on it.
Time and randomness
ctx.time and ctx.random give the same answers on every replay:
1@workflow(name="invoice")2async def invoice(ctx: WorkflowContext, customer: str) -> dict:3 number = ctx.random.uuid() # a str, the same on every replay4 reviewer = ctx.random.choice(["ana", "kofi", "lee"])5 issued_at = ctx.time.now() # when the engine journaled the start67 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")1112 if not ctx.replaying:13 log.info("invoice %s sent for review to %s", number, reviewer)1415 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, andctx.time.elapsed()is the difference.ctx.randomis seeded from the run's ids and offersrandom(),randint(a, b),choice(seq),shuffle(seq),sample(population, k)anduuid()(a string).ctx.replayingisTruewhile 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_idfor 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")2async 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"])67 if page["next_cursor"]:8 # Ends this run and starts a new one, with an empty journal, whose9 # input is the next cursor. Nothing after this line runs.10 ctx.restart_fresh(page["next_cursor"])1112 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:
1handle = await client.get_workflow("order-12345")23# Keep journal events 1 to 5, discard the rest, and run on from there.4new_execution_id = await handle.reset(target_event_id=5, reason="bad deploy")5print(f"new execution: {new_execution_id}")Find the event id with orcher workflow history:
1orcher workflow history order-12345Workflow metadata
1@workflow(name="describe-self", version="2.1")2async def describe_self(ctx: WorkflowContext) -> dict:3 info = ctx.info4 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 metrics11 }ctx.info also has attempt and started_at. ctx.execution returns the workflow_id and run_id as a WorkflowExecution.
WorkflowContext reference
| Method or property | Description |
|---|---|
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.time | Replay-safe clock: now(), started_at(), elapsed() |
ctx.random | Replay-safe random numbers |
ctx.replaying | Whether the code is catching up with the journal |
ctx.info / ctx.execution | WorkflowInfo / WorkflowExecution |
ctx.version | The @workflow version label |