In a CrewAI Flow, what do the @start and @listen decorators do?

## What a Flow is CrewAI has two layers. A **crew** is non-deterministic: agents with roles and tools decide, within a task, what to do and (in a hierarchical process) who does it next. A **Flow** is the deterministic layer wrapped around that. It is a normal Python class inheriting from `Flow` (imported as `from crewai.flow.flow import Flow, start, listen`), whose methods become steps in an event graph. Nothing about a Flow requires an LLM at all — a step can call a crew, hit a database, run a regex, or do nothing but transform state. The motivation is control. A single large crew hands the model both the *work* and the *order of the work*. When the order is actually known — fetch, enrich, validate, write — paying an LLM to rediscover it every run costs tokens, latency and predictability. Flows let you keep the model where judgment is needed and use plain code everywhere else. ## The @start decorator `@start()` marks an entry point. When you call `MyFlow().kickoff()`, **every** method decorated with `@start()` executes — there can be more than one, and each seeds its own branch of the graph. Note the parentheses: it is a decorator factory, so `@start()` and not `@start`. A start method takes no upstream argument (it has no trigger), but it can read values that `kickoff(inputs={...})` placed on `self.state`. ## The @listen decorator `@listen(trigger)` subscribes a method to the completion of another step. The trigger can be written as the method object inside the class body (`@listen(fetch_data)`) or as its name in a string (`@listen("fetch_data")`). When `fetch_data` returns, the listener is invoked. If the listener declares a single parameter beyond `self`, the upstream return value is passed into it; if it declares none, the return value is simply dropped and the listener is expected to read `self.state`. Listeners chain: a listener's own return value becomes the event that its listeners observe. A method may also be listened to by several listeners, which is how you fan out. And a method can be both a listener and a trigger, which is the normal case in the middle of a pipeline. ## Return values versus self.state Two channels carry data, and choosing badly is the most common design smell. - **Return value** — a point-to-point handoff to the immediate listener. Good for a small result the very next step consumes. - **`self.state`** — a shared object every step can read and write, and the only way for a step to see data produced by something that is not its direct trigger. State is either a plain dict or a Pydantic model, and CrewAI attaches an auto-generated `id` to it either way. A useful rule: return the thing that decides *what happens next*; put on state the thing that later steps *accumulate*. Threading a growing payload through return values across five steps produces methods whose signatures lie about what they need. ## Execution model Execution is event-driven, not a loop you write. `kickoff()` fires the start methods, collects their completion events, dispatches the listeners registered for them, and repeats until no step is pending. There is no scheduler, no polling and no implicit retry: if a step raises, the exception propagates out of `kickoff()` and downstream listeners never fire. Async is supported — a step may be declared `async def`, and `kickoff_async()` awaits the whole flow — but a plain `@listen` is not silently pushed to a background thread. Because the wiring is static, CrewAI can render it: `flow.plot()` writes an interactive HTML graph of the steps and edges, which is the fastest way to catch a listener wired to the wrong trigger. ## Typical shape A production flow usually looks like: one `@start` that normalizes the request onto state, a step that runs the first crew and stores its output, a `@router` that inspects that output, two or three branch steps that run different crews or none at all, and a final step that persists the result. The LLM-heavy parts are three or four bounded crew calls; everything between them is code you can unit-test. ## Failure modes The recurring bugs are: forgetting the parentheses on `@start()`; assuming a listener automatically receives state as its parameter (it receives the *trigger's return value*); writing a listener that mutates state assuming a sibling branch already ran, when nothing orders those two branches; and expecting a listener to fire twice because two different triggers exist — that needs an explicit `or_()` condition rather than two separate decorators.