Skip to main content

Workflows

Workflows provide durable execution so you can write programs that are resilient to any failure. Workflows help you write fault-tolerant background tasks, data processing pipelines, AI agents, and more.

You can make a function a workflow by annotating it with @DBOS.workflow(). Workflows call steps, which are Python functions annotated with @DBOS.step(). If a workflow is interrupted for any reason, DBOS automatically recovers its execution from the last completed step.

Here's an example of a workflow:

@DBOS.step()
def step_one():
print("Step one completed!")

@DBOS.step()
def step_two():
print("Step two completed!")

@DBOS.workflow()
def workflow():
step_one()
step_two()

Starting Workflows In The Background​

One common use-case for workflows is building reliable background tasks that keep running even when the program is interrupted, restarted, or crashes. You can use DBOS.start_workflow to start a workflow in the background. If you start a workflow this way, it returns a workflow handle, from which you can access information about the workflow or wait for it to complete and retrieve its result.

Here's an example:

@DBOS.workflow()
def background_task(input):
# ...
return output

# Start the background task
handle: WorkflowHandle = DBOS.start_workflow(background_task, input)
# Wait for the background task to complete and retrieve its result.
output = handle.get_result()

After starting a workflow in the background, you can use DBOS.retrieve_workflow to retrieve a workflow's handle from its ID. You can also retrieve a workflow's handle from outside of your DBOS application with DBOSClient.retrieve_workflow.

If you need to run many workflows in the background and manage their concurrency or flow control, you can also use DBOS queues.

Workflow IDs and Idempotency​

Every time you execute a workflow, that execution is assigned a unique ID, by default a UUID. You can access this ID through the DBOS.workflow_id context variable. Workflow IDs are useful for communicating with workflows and developing interactive workflows.

You can set the workflow ID of a workflow with SetWorkflowID. Workflow IDs must be globally unique for your application. An assigned workflow ID acts as an idempotency key: if a workflow is called multiple times with the same ID, it executes only once. This is useful if your operations have side effects like making a payment or sending an email. For example:

@DBOS.workflow()