CrewAI — role-based crews

You have seen multi-agent orchestration as a pattern — a supervisor handing work to specialists. CrewAI is a framework that makes that pattern feel like staffing a small team. You don’t draw a graph of nodes and edges; you hire agents by role, give each a task, and pick how they work together. For a class of problems that decompose into clear job titles — researcher, writer, editor — it is the fastest way from idea to working crew.

Four primitives

CrewAI’s whole mental model is four objects:

The role/goal/backstory triple isn’t decoration — it is the system prompt. “You are a Senior Research Analyst who is meticulous and cites sources” steers the model as surely as any hand-written instruction, just expressed as a job description.

The shape of a crew

Here is a two-agent crew: a researcher gathers facts, a writer turns them into a summary. Read it as the canonical CrewAI shape.

# requires: pip install crewai
from crewai import Agent, Task, Crew, Process

# 1. Hire agents by role. role + goal + backstory become the system prompt.
researcher = Agent(
    role="Senior Research Analyst",
    goal="Find the 3 most important, current facts about {topic}",
    backstory="You are meticulous and always cite your sources.",
    llm="gpt-4.1",
)
writer = Agent(
    role="Tech Writer",
    goal="Turn research notes into a tight, plain-English summary",
    backstory="You write plainly. No marketing language, no fluff.",
    llm="gpt-4.1",
)

# 2. Define tasks. expected_output tells the agent when it's done.
research = Task(
    description="Research {topic}. List 3 key facts.",
    expected_output="3 bullet points, each with a source.",
    agent=researcher,
)
write = Task(
    description="Write a 100-word summary from the research notes.",
    expected_output="A single ~100-word paragraph.",
    agent=writer,
    context=[research],   # the writer receives the researcher's output
)

# 3. Assemble the crew and pick how they collaborate.
crew = Crew(
    agents=[researcher, writer],
    tasks=[research, write],
    process=Process.sequential,
)

# result = crew.kickoff(inputs={"topic": "vector databases"})
# kickoff fills the {topic} placeholder, runs research, then write.
print("Shape only — kickoff needs a model API key to actually run.")

Two things to notice. The {topic} placeholder in a goal or description is filled at kickoff(inputs=...) time, so one crew definition is reusable across topics. And context=[research] is the wiring that matters: it hands the writer the researcher’s output, turning two isolated agents into a pipeline.

Sequential vs hierarchical

The Process is the one real decision. CrewAI gives you two:

• Sequential runs the tasks in the order you listed them, each output feeding the next. Use it when the workflow is a known assembly line: research, then write, then edit.
• Hierarchical adds a manager agent (CrewAI spins one up from a manager LLM) that decides which agent handles what, in what order, and can loop back. Use it when the decomposition isn’t fixed in advance and someone needs to coordinate.

If the steps are a fixed line that always runs once, sequential is simpler and more predictable. The moment you need a coordinator to judge the fact-check and decide whether to loop back for revision, that dynamic routing is exactly what the hierarchical manager is for.

Where CrewAI fits

In one breath

• CrewAI models multi-agent work as staffing a team: four primitives — Agent, Task, Crew, Process.
• An agent’s role + goal + backstory is its system prompt; a task’s expected_output tells it when it’s done.
• context=[...] wires one task’s output into another — the difference between isolated agents and a real pipeline.
• Process is the key choice: sequential (fixed assembly line) vs hierarchical (a manager agent delegates and can iterate).
• Reach for CrewAI for clear role-based collaboration; choose LangGraph for fine-grained state/branching control and the OpenAI Agents SDK for lighter handoffs. A single agent doesn’t need a crew.

Quick check

Next

CrewAI is one opinionated framework. Next, a different one from Anthropic: the Claude Agent SDK and its loop of gathering context, taking action, and verifying work.