LlamaIndex Workflow Utils

0.10.1 verified Fri May 01 auth: no python

Utility library for defining and running workflows in LlamaIndex. Provides the `Workflow` class, `step` decorator, and event-based orchestration. Current version is 0.10.1, actively maintained as part of LlamaIndex ecosystem. Release cadence follows LlamaIndex releases.

pip install llama-index-utils-workflow

Common errors

error ImportError: cannot import name 'Workflow' from 'llama_index.utils.workflow' ↓

cause The Workflow class was moved to llama_index.core.workflow in version 0.10.0.

fix

Use from llama_index.core.workflow import Workflow instead.

error AttributeError: 'NoneType' object has no attribute 'event' ↓

cause A step method returned None instead of an event object.

fix

Ensure each step returns an event (e.g., return StopEvent(result=...)) or return None only if explicitly handling the absence of event.

error RuntimeError: Workflow timed out after 10 seconds ↓

cause Default timeout is 10 seconds, which may be too short for long-running steps or external API calls.

fix

Set a higher timeout when instantiating the workflow: MyWorkflow(timeout=120).

error TypeError: step() got multiple values for argument 'self' ↓

cause Step method defined as a regular function instead of an instance method (missing `self` parameter) or incorrectly decorated.

fix

Define step methods as instance methods with self as first argument and use @step decorator inside the Workflow class.

Warnings

breaking The `Workflow` class and `step` decorator were moved from `llama_index.utils.workflow` to `llama_index.core.workflow` in llama-index>=0.10.0. Old imports from the utils package will fail. ↓

fix Change imports to `from llama_index.core.workflow import Workflow, step`.

deprecated The `llama_index.utils.workflow` module is deprecated and may be removed in a future release. All workflow functionality is now in llama-index-core. ↓

fix Use `from llama_index.core.workflow import Workflow, step, Context, StartEvent, StopEvent` instead.

gotcha Workflow step methods must be async and return an event. Mixing sync/async or returning None can cause silent failures. ↓

fix Ensure all step methods are `async def` and return an event (e.g., `StopEvent` or custom event). Use `await` when calling other async functions inside steps.

gotcha The `timeout` parameter in `Workflow.__init__` is in seconds. A common mistake is setting it too low for complex workflows, causing early termination. ↓

fix Increase timeout (e.g., `timeout=120`) or set to `None` for no timeout (not recommended in production).

Imports

Workflow

wrong

from llama_index.utils.workflow import Workflow

correct

from llama_index.core.workflow import Workflow

Workflow class is exported from llama-index-core, not from this utils package.

step

wrong

from llama_index.utils.workflow import step

correct

from llama_index.core.workflow import step

The step decorator is part of core workflow, not this utils package.

Context

wrong

from llama_index.utils.workflow import Context

correct

from llama_index.core.workflow import Context

Context is imported from core workflow module.

StartEvent, StopEvent

wrong

from llama_index.utils.workflow import StartEvent

correct

from llama_index.core.workflow import StartEvent, StopEvent

Event classes are in core, not utils.

Quickstart

Define a simple workflow using the Workflow class and step decorator. Note: The 'llama-index-utils-workflow' package itself provides additional utilities (e.g., drawing, events), but the core workflow classes are in llama-index-core.

import os
from llama_index.core.workflow import Workflow, step, Context, StartEvent, StopEvent

class MyWorkflow(Workflow):
    @step
    async def my_step(self, ctx: Context, ev: StartEvent) -> StopEvent:
        return StopEvent(result="done")

w = MyWorkflow(timeout=10, verbose=False)
result = await w.run()
print(result)