Three agents work behind a single prompt. One reads the source documents and pulls out the numbers. One turns those numbers into a draft. One goes back through the draft hunting for claims that don’t match the sources. You press enter once, and eight minutes later there’s a document a person would have spent half a day assembling.
That’s the pitch for CrewAI, and it mostly holds up. The CrewAI Python framework wraps multi-agent work in a vocabulary borrowed from hiring: roles, goals, backstories, tasks. Instead of hand-chaining prompts inside your own script, you describe a small team and let the framework route work between its members.
Roles, Goals, Backstories: What an Agent Really Is
A CrewAI agent is a system prompt with an attitude and a toolbox. You define it with four fields that matter, plus a couple that are optional.
- role — the job title, e.g. “Senior Compliance Reviewer”
- goal — what this agent is optimising for, in one sentence
- backstory — the seasoning: “Twelve years reading financial disclosures and flagging vague language.”
- tools — a web search, a SQL query, a document reader, a custom Python function
People underestimate the backstory field. It sounds like flavour text, but it changes output. An agent told it spent a decade in regulatory review writes differently than one told it is a “helpful assistant” given the same task. Keep it short and specific. Two sentences of real experience beats a paragraph of adjectives.
Each agent runs its own loop with its own context window. They don’t share a brain. That’s the single most important thing to internalise about CrewAI agents, because it explains both the power and the weird failures: two agents can hold contradictory facts and never notice.
Tasks Are Where the Actual Work Lives
Agents are personalities. Tasks are the job. Every task needs a description, and it should have an expected_output — the field most tutorials skip and most production crews can’t live without.
Writing “Research the competitor pricing landscape” gets you mush. Writing “Research competitor pricing for the four vendors named in the brief, and return a markdown table with vendor, tier, monthly price and contract minimum” gets you something you can parse, test and store. The expected_output field also gives you a natural place to enforce format, which cuts downstream parsing failures sharply.
Tasks can also declare context, which passes the output of earlier tasks into later ones. That’s the plumbing that makes a researcher’s notes actually reach the writer instead of evaporating.
Sequential vs Hierarchical: The Process Decision
Set process=Process.sequential and tasks run in the order you listed them, each one handled by its assigned agent. Simple, cheap, predictable. Set it to hierarchical and CrewAI adds a manager agent, driven by the manager_llm you choose, that decides who does what and can delegate.
Hierarchical crews are impressive in demos and expensive in production. A three-task sequential crew might make six to ten LLM calls including tool use and retries. The same crew run hierarchically can double that, because the manager burns tokens reasoning about assignments before anyone does any work. If your task order is already known, sequential wins on cost and debuggability nearly every time. The broader playbook for choosing between these patterns is covered in this guide to AI agent orchestration, and it applies well beyond CrewAI.
The Flows layer
CrewAI later added Flows, an event-driven layer that lets you put deterministic control flow around crews: branches, loops, state that persists between steps. It’s the answer to the obvious objection that LLM-driven routing is too slippery for anything with compliance requirements. Use a Flow when the sequence is fixed, and hand control to a crew only for the fuzzy middle part.
Where CrewAI Agents Earn Their Keep
Crews shine when a job naturally decomposes into specialisms with a handoff between them, and when the handoffs are forgiving enough to survive a slightly sloppy summary.
- Content pipelines: researcher drafts a brief, writer expands it, editor checks claims against sources
- Support triage: a classifier sorts the ticket, a specialist drafts the reply, a reviewer checks policy compliance
- Code review: one agent checks logic, another checks test coverage, a third writes the fix summary
- Data enrichment: a scraper pulls records, a cleaner normalises them, a validator flags anything suspicious
The pattern is always the same. Two to four distinct jobs, a clear artefact passed between them, and at least one step where a second opinion genuinely improves the result. If you can’t name the artefact, you don’t need a crew.
The Failure Modes Nobody Warns You About
The most common one is politeness. An editor agent handed a writer agent’s draft tends to approve it. Models are agreeable by default, and a review step that never rejects anything is just a token tax. Fix it by giving the reviewer an explicit rubric, telling it to return PASS or FAIL first, and logging the verdicts. If the fail rate is zero across fifty runs, your reviewer is decorative.
Second: loops. An agent with a search tool and no iteration cap will happily make eleven searches before deciding it has enough. Set max_iter low, watch the logs, and only raise it when you can see it needs the room.
Third: context bloat. Long task outputs get pasted into the next agent’s prompt whole. Two pages of research notes become three of near-duplicates by the time the writer sees them. Ask agents for compressed outputs with a hard word limit, then expand only where it matters. There’s a longer treatment of building agents you can actually trust in this walkthrough on building AI agents with Python.
The Cost Math Is Not Trivial
A crew doing a 1,200-word research brief typically lands between six and twelve model calls once tool use and retries are counted. On a small, fast model that’s a few cents. On a frontier model over long documents it can reach 20 to 40 cents per run, and a batch of 500 briefs becomes a real line item.
The usual fix is tiering. Give the researcher a cheap model with a big context window, give the writer the expensive one, and let the editor use the cheap model with a tight rubric. CrewAI makes per-agent model selection easy, which is one of its better design choices. Add caching for repeated lookups and you’ll often cut spend by more than half.
When CrewAI Is the Wrong Choice
If one well-written prompt plus two function calls solves the problem, a crew of four agents will be slower, pricier and harder to debug. If the steps are fully deterministic, a plain Python pipeline is better in every dimension. Crews are for work where the judgement is genuinely distributed and the output benefits from multiple passes with different instructions.
For heavier environments, the question shifts from “does the framework work” to “does it hold up under load, with observability, retries and access control.” That’s a different evaluation, and this comparison of enterprise AI agent platforms under production load is a reasonable starting point before you commit a team to one.
Start With Two Agents, Not Five
The strongest predictor of whether a CrewAI project ships is how small the first version is. Two agents, one task each, one artefact passed between them. Run it twenty times on real inputs. Read the intermediate output every single time, because that’s where the bugs live. Only add a third agent when you can point at something specific the first two keep getting wrong, and name the job that would fix it.
Don’t skip the boring parts either: an expected_output on every task, a max_iter on every agent, logs written to disk, and a test set of five inputs you run after every prompt change. Frameworks like CrewAI make it easy to spin up impressive-looking crews. The teams that get value are the ones that resist that and treat each new agent as a line of code that has to justify itself. If this is your first build, there’s a sensible order to learn things in, and this roundup of AI agents for beginners will save you a few weekends of false starts.