---
id: llama-index-workflows
version: "2.23.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# llama-index-workflows — An event-driven, async-first, step-based way to control the execution flow of AI applications like Agents.

License: permissive · Maintenance: active · Downloads: 12.2M/mo

## What it is and what it does

LlamaIndex Workflows is a framework for building complex, multi-step AI applications using an async-first, event-driven architecture. It lets you define workflows as a series of steps—async functions that process events and emit new events to other steps—with built-in state management so each workflow run is self-contained and can be serialed and resumed. The framework handles routing between capabilities, parallel processing, looping, and state persistence, and automatically instruments workflows for observability with tools like Arize Phoenix and OpenTelemetry.

You define workflows by subclassing Workflow and decorating async methods with @step, specifying which events they accept and which they emit. Steps that accept StartEvent run first, steps that emit StopEvent end the workflow, and intermediate events pass data between steps. A Context object lets you share state and information across steps within a single run. The async-first design means workflows integrate naturally with async frameworks like FastAPI and Jupyter Notebooks.

Use it for:

- Build AI agents that reason, make decisions, and take actions across multiple steps with state preservation.
- Create document processing pipelines that ingest, analyze, summarize, and route documents through processing stages.
- Coordinate between different AI models (LLMs, vision models) to solve complex tasks in a single workflow.
- Develop research assistants that search, analyze, synthesize information, and provide comprehensive answers.
- Build customer support automation systems that route, categorize, and respond to inquiries intelligently.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

An async-first, event-driven framework for orchestrating multi-step AI workflows with state management and built-in observability instrumentation.

Yes. The package is actively maintained, has low install friction, carries a permissive MIT license, and fills a clear need for orchestrating complex AI workflows. It's well-suited for production AI applications that require multi-step reasoning, state management, and observability. Start with it if you're building agents, document pipelines, or multi-model AI systems that need reliable async coordination.

## Install

pip install llama-index-workflows
uv add llama-index-workflows
poetry add llama-index-workflows

## Installing llama-index-workflows

Before you install: Low friction installation with only three runtime dependencies (pydantic, llama-index-instrumentation, typing-extensions). Package is actively maintained with a recent release.

License in practice: MIT license permits unrestricted use, modification, and distribution in both open-source and commercial projects.

Quickstart:

pip install llama-index-workflows

import asyncio
from pydantic import BaseModel
from workflows import Context, Workflow, step
from workflows.events import StartEvent, StopEvent

class MyWorkflow(Workflow):
    @step
    async def start(self, ctx, ev: StartEvent) -> StopEvent:
        return StopEvent(result=ev.input_msg)

asyncio.run(MyWorkflow().run(input_msg="test"))

Requires Python 3.10 or later; workflows are async-first and work best in async contexts like FastAPI or Jupyter Notebooks.

Verify before relying:

- Whether llama-index-instrumentation is a required dependency or optional for observability features
- Performance characteristics and scalability limits for large numbers of concurrent workflow runs
- Integration requirements with Arize Phoenix and OpenTelemetry mentioned in the description

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 12.2M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

async workflow orchestration, event-driven AI pipeline, multi-step process automation, AI agent framework, state management workflows, async task coordination, step-based execution control, async-orchestration, ai-workflows, event-driven

[View on SkillFed](https://skillfed.io/packages/llama-index-workflows) · [View on PyPI](https://pypi.org/project/llama-index-workflows/)