Principle:CrewAIInc CrewAI Flow Class Definition

Overview

Flow Class Definition is an event-driven programming pattern where methods within a class are declared as entry points, listeners, or routers using decorators, forming a directed execution graph that the runtime traverses automatically.

Description

In CrewAI's Flow system, developers define workflows by subclassing the Flow base class and decorating methods with @start, @listen, and @router. These decorators declaratively define the execution graph:

• @start() -- Marks a method as an entry point. When flow.kickoff() is called, all @start methods execute concurrently. A start method can optionally specify a condition, making it a conditional entry point that triggers when another method completes.
• @listen(condition) -- Registers a method as a listener that fires when the specified condition is met. The condition can be a method reference, a method name string, or a composite condition built with or_() / and_().
• @router(condition) -- Declares a routing method that executes when its condition is met and returns a string value. That return value is then used to select which downstream @listen methods fire next (those listening for that specific string).

Methods can be synchronous or asynchronous (async def). The framework detects coroutine functions and awaits them transparently. All methods share access to self.state for reading and writing flow data.

The FlowMeta metaclass processes the class definition at class-creation time, scanning all attributes for decorator metadata and building internal registries (_start_methods, _listeners, _routers, _router_paths). This means the execution graph is fully resolved before any instance is created.

Theoretical Basis

Flow Class Definition implements Event-Driven Architecture with a Directed Acyclic Graph (DAG) execution model:

• Nodes are the decorated methods within the flow class
• Edges are the relationships defined by decorator parameters (e.g., @listen(method_a) creates an edge from method_a to the decorated method)
• Execution follows a topological traversal: start methods fire first, their completions trigger listeners, which in turn trigger further listeners

This pattern is distinct from imperative pipeline execution (as used in CrewAI's sequential/hierarchical crew processes) because:

1. The execution order is determined by event propagation, not code order
2. Multiple paths can execute concurrently when a method triggers multiple listeners
3. Routers introduce conditional branching based on runtime values

Pattern Element	Flow Mapping
Event Source	@start method completing and returning a value
Event Listener	@listen method triggered by a source's completion
Event Router	@router method that selects downstream paths via return value
DAG Nodes	All decorated methods in the flow class
DAG Edges	Decorator parameter relationships (method references, strings, combinators)

Usage

When to Use Flow Class Definition

• When building multi-step workflows where steps have data dependencies
• When different execution paths should be taken based on intermediate results
• When parallel execution of independent steps is desired
• When combining multiple crew executions with custom logic between them

Structure of a Flow Class

1. Subclass Flow[T] where T is the state type
2. Define one or more @start() methods as entry points
3. Define @listen(condition) methods for downstream processing
4. Optionally define @router(condition) methods for branching
5. Call flow.kickoff() to begin execution

Constraints

• At least one @start() method must be defined; otherwise kickoff() has nothing to execute
• Listener conditions must reference methods that exist in the same flow class (or valid string constants from routers)
• Circular dependencies between listeners are permitted but developers must ensure termination conditions
• Methods can accept a single positional argument (the result from the triggering method) or no arguments beyond self

Related Pages

• Implementation:CrewAIInc_CrewAI_Flow_Decorators
• Principle:CrewAIInc_CrewAI_State_Model_Design -- State containers shared across flow methods
• Principle:CrewAIInc_CrewAI_Conditional_Routing -- Advanced routing and fan-in/fan-out patterns
• Principle:CrewAIInc_CrewAI_Crew_Integration_In_Flow -- Embedding crew executions within flow methods
• Principle:CrewAIInc_CrewAI_Flow_Execution_And_Visualization -- Runtime execution and graph visualization