« Phase 19 README · Warmup · Deep Dive · Principal Deep Dive · Core Contributor · Staff Notes

Phase 19 — Hitchhiker's Guide

The compressed practitioner tour. Read the WARMUP for the mechanism; this is the stuff you say in the meeting.

30-second mental model

CrewAI builds teams of role-playing agents. You cast agents by role / goal / backstory, give each a Task, group them into a Crew, pick a Process, and call kickoff(inputs). The process is the execution model: sequential runs listed tasks in order with no LLM deciding flow (cheap, deterministic); hierarchical adds a manager LLM that delegates each task and synthesizes (flexible, but N+1 extra LLM calls). Tasks share work through context (feed-forward by default). Separately, Flows are event-driven orchestration — @start / @listen / @router, or_/and_, persisted state — that wire multiple crews together with branching and human-in-the-loop. Crews are the sequences; Flows are the conductor.

The facts to tattoo on your arm

FactWhy it matters
Process.sequential = listed order, no manager, N LLM callsthe cheap, deterministic default
Process.hierarchical = manager delegates + synthesizes, N+1 manager calls on top of N workersthe manager is not free
context=None → feed-forward · [t1,t3] → fan-in · [] → isolatedthe top source of subtle crew bugs
{placeholders} interpolated from kickoff(inputs=)one crew definition, many runs
CrewOutput.raw = last task · .tasks_output = all taskshow you read a result
@listen(m) fires on m's completion and receives m's outputchaining + data flow in a Flow
@router emits a label; @listen("label") catches itbranching in a Flow
or_ = fire on ANY · and_ = fire on ALLeither-path join vs fan-in gate
structured state = Pydantic model (typed, id) · unstructured = dict (id)schema vs flexibility
@persist = save state per step (SQLite, keyed by id) → resumabledurability + HITL
each Flow method fires at most oncewhy the event graph always terminates

Framework one-liners

  • CrewAI = roles + crews + process; Flows for orchestration. Fastest to a role-based team.
  • LangGraph = an explicit graph over shared state (Pregel/BSP, reducers, checkpointers). Reach for it when you need explicit state and control.
  • AutoGen = agents conversing (group chat). Reach for it when the task is a dialogue.
  • All three still wrap the same machine: an untrusted LLM in a loop, tool calls crossing the trust boundary, reliability compounding 0.95^n. The framework is ergonomics, not physics.

The "which process?" decision

Is the task/agent order known ahead of time and non-branching?
  ├─ yes → Process.sequential   (cheap, deterministic; the default)
  └─ no, need runtime routing across specialists + reconciliation?
        └─ yes → Process.hierarchical  (accept N+1 manager calls; instrument tokens)
Need branching / multiple crews / wait-on-human / durability?
  └─ that's a Flow, not a bigger Crew.

War stories

  • The crew whose summary was always half-right. A three-source research crew's summarizer left context at its feed-forward default, so it only ever read the last source, not all three. One line — context=[src_a, src_b, src_c] — fixed it. Context is the #1 silent CrewAI bug.
  • The hierarchical bill. A team flipped a 6-task crew to hierarchical because it "coordinated better," and the token bill jumped ~2x. Nobody had counted the N+1 manager calls plus the per-task tool loops. It went back to sequential with one hierarchical sub-crew, deliberately.
  • The manager who delegated to a ghost. A manager LLM hallucinated a worker role that didn't exist; the crew silently produced nothing useful. Delegation to an unknown worker must be a hard error you can see — not a no-op.
  • The "one giant agent" refund bot. Rebuilt as a sequential Crew (triage→draft→review) inside a Flow with a @router on the refund amount and a @persisted human-approval gate. Cheaper, auditable, and it survived restarts. Flows earn their keep exactly here.

Vocabulary

Agent (role/goal/backstory + llm + tools) · Task (description, expected_output, agent, context) · Crew (agents + tasks + process) · Process (sequential | hierarchical) · kickoff(inputs) · CrewOutput / TaskOutput (.raw, .tasks_output) · context (feed-forward / fan-in / isolated) · manager_llm / manager_agent (hierarchical coordinator) · Flow (event-driven orchestration) · @start / @listen / @router · or_ / and_ · structured vs unstructured state · @persist (SQLite) · Crews-inside-Flows.

Beginner mistakes

  1. Thinking CrewAI is Crews — missing Flows entirely.
  2. Reaching for hierarchical because it sounds smarter, without counting the N+1 manager calls.
  3. Leaving context at feed-forward when you needed a fan-in (or isolation).
  4. Treating expected_output as optional — it's the target that sharpens the agent.
  5. Using str.format-style interpolation that KeyErrors on literal braces in a description.
  6. Expecting a @router to pass data to the branch — it passes a label; data goes via state.
  7. Not instrumenting token_usage — then getting surprised by tool loops + manager overhead.
  8. Building "one autonomous agent" for a task that's a fixed pipeline with one fuzzy step.