DS DevShelfHub Projects · AI tools
Tutorials / CrewAI / Reference / Decorators / @listen
Decorator crewai.flow.flow

@listen: Reference Guide

By DevShelfHub

Subscribes a Flow method to the completion of another method or named output.

See the CrewAI API reference index, CrewAI introduction, hooks and events tutorial, and core concepts for surrounding context.

What is @listen?

@listen declares a downstream Flow method that should run once its upstream producers finish. The argument can be another decorated method reference, a string label tied to router output, or a composite from and_() / or_() describing conjunctive or disjunctive triggers. The framework passes the upstream return value into your listener so you can transform data without stuffing transient blobs into global state unless you choose to.

Fan-in with and_() is the idiomatic way to synchronize parallel branches — for example waiting for both a cache warmer and a permissions check before drafting a response. or_() covers cases where multiple exclusive producers might fire depending on runtime conditions, preventing dead listeners when only one branch executes.

Listeners should remain focused orchestration steps: call crews, hit tools, or reshape payloads, then return values that downstream routers or additional listeners can consume. Keep heavy retries inside the invoked services, not duplicated across multiple listeners that would multiply load during partial failures.

When to Use

To chain Flow steps based on data dependencies.

Use Cases

  • • Sequential chaining
  • • Fan-in patterns with and_()
  • • Either-or triggers with or_()

Key Features

  • ✓ Single or multiple sources
  • ✓ and_/or_ combinators
  • ✓ Receives upstream output

When NOT to Use

When you actually need conditional branching — use @router.

Notes

Dead listeners

If every upstream is gated and none fire, the listener never runs. Add telemetry on branch selection and fallbacks for empty or_ sets so operators can see stuck flows quickly.

Payload size between steps

Returning huge strings or binary blobs through listener arguments can balloon memory. Persist large artifacts externally and pass handles on Flow state instead of raw content.

Ordering with routers

Router-tagged outputs require listeners that match exact string labels. Typos silently drop edges; centralize tag constants in a small module shared by router and listener methods.

Testing graphs locally

Exercise listener wiring with minimal Flow subclasses that stub upstream methods to return fixtures. This catches missing and_/or_ combinations faster than integration tests alone.

Import

python 
from crewai.flow.flow import listen, and_, or_

How to Apply

python 
@listen(begin)
def next_step(self, prev):
    return process(prev)

What It Enables

  • ✓ Data-flow chaining
  • ✓ Fan-in synchronization

Code Examples

Chain

python 
@listen(begin)
def next_step(self, prev):
    return prev.upper()

Fan-in

python 
@listen(and_(fetch_a, fetch_b))
def combine(self):
    return self.state

Disjunctive trigger

python 
@listen(or_(from_cache, from_network))
def normalize(self, payload):
    return normalize_record(payload)

Integration Patterns

After @start
Combined with @router for branching

Common Mistakes

❌ Listening to a method that never runs because its trigger is conditional

✅ Use or_() to listen to multiple possible upstreams.

Related: Task class reference, Agent class reference, and the first Crew tutorial.

@listen FAQ

What is @listen in CrewAI?

Subscribes a Flow method to the completion of another method or named output. @listen declares a downstream Flow method that should run once its upstream producers finish. The argument can be another decorated method reference, a string label tied to router output, or a composite from and_() / or_() describing conjunctive or disjunctive triggers. The framework passes the upstream return value into your listener so you can transform data without stuffing transient blobs into global state unless you choose to. Fan-in with and_() is the idiomatic way to …

Which module defines the CrewAI decorator @listen?

DevShelfHub maps @listen to Python module crewai.flow.flow. Pin your installed crewai version and match imports to the import snippet on this page.

When should I use @listen?

To chain Flow steps based on data dependencies.

When should I avoid @listen?

When you actually need conditional branching — use @router.

How do I apply @listen in Python?

@listen(begin) def next_step(self, prev): return process(prev)

Where can I explore more CrewAI API reference pages?

Open the CrewAI API reference index on DevShelfHub to search classes, methods, and decorators, each with runnable examples, parameters, common mistakes, and cross-links.