{"id":23983,"library":"llama-index-utils-workflow","title":"LlamaIndex Workflow Utils","description":"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.","status":"active","version":"0.10.1","language":"python","source_language":"en","source_url":"https://github.com/run-llama/llama_index","tags":["llama-index","workflow","utilities","ai","orchestration"],"install":[{"cmd":"pip install llama-index-utils-workflow","lang":"bash","label":"pip install"}],"dependencies":[{"reason":"Core LlamaIndex library required for base classes and event system","package":"llama-index-core","optional":false}],"imports":[{"note":"Workflow class is exported from llama-index-core, not from this utils package.","wrong":"from llama_index.utils.workflow import Workflow","symbol":"Workflow","correct":"from llama_index.core.workflow import Workflow"},{"note":"The step decorator is part of core workflow, not this utils package.","wrong":"from llama_index.utils.workflow import step","symbol":"step","correct":"from llama_index.core.workflow import step"},{"note":"Context is imported from core workflow module.","wrong":"from llama_index.utils.workflow import Context","symbol":"Context","correct":"from llama_index.core.workflow import Context"},{"note":"Event classes are in core, not utils.","wrong":"from llama_index.utils.workflow import StartEvent","symbol":"StartEvent, StopEvent","correct":"from llama_index.core.workflow import StartEvent, StopEvent"}],"quickstart":{"code":"import os\nfrom llama_index.core.workflow import Workflow, step, Context, StartEvent, StopEvent\n\nclass MyWorkflow(Workflow):\n    @step\n    async def my_step(self, ctx: Context, ev: StartEvent) -> StopEvent:\n        return StopEvent(result=\"done\")\n\nw = MyWorkflow(timeout=10, verbose=False)\nresult = await w.run()\nprint(result)","lang":"python","description":"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."},"warnings":[{"fix":"Change imports to `from llama_index.core.workflow import Workflow, step`.","message":"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.","severity":"breaking","affected_versions":">=0.10.0"},{"fix":"Use `from llama_index.core.workflow import Workflow, step, Context, StartEvent, StopEvent` instead.","message":"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.","severity":"deprecated","affected_versions":">=0.10.0"},{"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.","message":"Workflow step methods must be async and return an event. Mixing sync/async or returning None can cause silent failures.","severity":"gotcha","affected_versions":"all"},{"fix":"Increase timeout (e.g., `timeout=120`) or set to `None` for no timeout (not recommended in production).","message":"The `timeout` parameter in `Workflow.__init__` is in seconds. A common mistake is setting it too low for complex workflows, causing early termination.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use `from llama_index.core.workflow import Workflow` instead.","cause":"The Workflow class was moved to llama_index.core.workflow in version 0.10.0.","error":"ImportError: cannot import name 'Workflow' from 'llama_index.utils.workflow'"},{"fix":"Ensure each step returns an event (e.g., `return StopEvent(result=...)`) or `return None` only if explicitly handling the absence of event.","cause":"A step method returned None instead of an event object.","error":"AttributeError: 'NoneType' object has no attribute 'event'"},{"fix":"Set a higher timeout when instantiating the workflow: `MyWorkflow(timeout=120)`.","cause":"Default timeout is 10 seconds, which may be too short for long-running steps or external API calls.","error":"RuntimeError: Workflow timed out after 10 seconds"},{"fix":"Define step methods as instance methods with `self` as first argument and use `@step` decorator inside the Workflow class.","cause":"Step method defined as a regular function instead of an instance method (missing `self` parameter) or incorrectly decorated.","error":"TypeError: step() got multiple values for argument 'self'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}