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()