An introduction to CrewAI

CrewAI is an open-source Python framework for multi-agent systems, created in 2023 by João Moura and MIT-licensed. It is one of the most widely deployed frameworks in this space — reportedly used inside a majority of the US Fortune 500, running hundreds of millions of agent executions a month.

It has two distinct modes, and choosing correctly between them is most of the skill in using it well.

Crews: agents with roles

The original idea. You define agents as role-playing units — each with a role, a goal, a backstory and a set of tools. A Researcher, a Writer, an Analyst. Tasks are atomic units of work with a description, an expected output, an assigned agent, and optionally context carried from earlier tasks.

A crew is a team of those agents collaborating, dividing the work by role. The appeal is that it maps onto how people already think about delegation, which makes it unusually easy to explain to a stakeholder.

The caution is that the role metaphor can do more work in your head than in the system. Giving an agent the backstory of a twenty-year veteran analyst does not grant it twenty years of judgement. What roles genuinely do is scope: a narrower role means a narrower tool set and a more focused context, and that is why it improves output. Treat the backstory as context engineering rather than character work and you will write better ones.

Flows: when the sequence has to be right

Flows are the event-driven, stateful layer added later, giving explicit control over how steps are triggered and sequenced and how state passes between them.

The split is clean:

Use a crew when you genuinely do not know the right sequence — exploratory research, open-ended analysis. Use a flow when you do, and need it to happen the same way every time.

Interoperability

CrewAI supports the Model Context Protocol and the Agent-to-Agent standard, so tools you expose over MCP are reachable without framework-specific adapters. That materially reduces the lock-in — your tools stay portable even if the orchestration does not.

When to reach for it

It fits when your problem genuinely decomposes into different kinds of work handled by differently-configured agents, when you want that structure legible to people who will not read your code, and when you are in Python already.

It fits badly for a single agent with a handful of tools. As argued at more length in pick a framework, or pick a loop, that case is a while-loop and the framework is overhead you will pay for in debugging. Multi-agent structure is a cost you take on for a reason, not a starting position.

Two things that catch people out

• Multiple agents multiply cost. Five agents collaborating means five sets of context and a lot of inter-agent chatter. A crew can cost several times what a single well-prompted agent costs for the same result. Measure before you assume the structure is helping.
• Delegation loops. Agents that can hand work to each other can hand it back and forth. Bound the iterations and watch the traces early — this is the multi-agent version of the pointless retry loop covered in the harness piece.

Getting started sensibly

1. Build the single-agent version first. Establish what one well-configured agent achieves.
2. Identify a specific failure that more structure would fix.
3. Add the second agent for that reason. Measure whether it helped.
4. Move the parts you now understand into a Flow so they run the same way every time.

That sequence produces systems that are cheaper, easier to debug, and considerably more likely to still be running in six months than the ones that begin with an eight-agent org chart.