Multi-Agent Orchestration with CrewAI

The CrewAI model: role-play as architecture essential

Picture how a good newsroom ships a story. A reporter chases down the facts, a writer shapes them into prose, an editor tightens and checks it before it runs. Nobody does all three jobs at once, and nobody starts from a blank page — each person receives the previous person's work and adds their specialty. That division of labour is exactly what CrewAI encodes: instead of one over-stuffed prompt trying to research and write and review, you spin up a small team where each member is narrow, sharp, and hands its output to the next.

Why bother splitting the work at all? Because a single prompt that tries to do everything tends to do each part a little worse — it forgets the tone halfway through, or drops sources when it starts writing. Giving each concern its own agent, its own instructions, and its own clear "done" target keeps every step focused, and it makes the pipeline legible: when the brief comes out weak you can see whether the research was thin or the writing was sloppy, and fix just that stage. This is the same instinct behind splitting a monolith into functions — smaller units, clearer contracts, easier debugging.

But here's the honest warning, and it's the theme of this whole chapter: a team is not free. Every extra agent is another LLM call, more tokens, more latency, and one more place for context to get lost in the hand-off. The classic beginner mistake is to reach for a crew because it looks sophisticated, when a single well-equipped agent would have been cheaper, faster, and just as good. Multi-agent earns its keep only when the work genuinely breaks into distinct specialties — hold that gate in your head as you read on (we make it explicit in the "do you need a crew?" section below).

CrewAI's core metaphor is a team of specialists. You define agents by role, give each a goal and a backstory, hand them tasks, and assemble them into a crew that runs under a process (sequential or hierarchical). The role/goal/backstory isn't fluff — it's how you steer each agent's behavior, exactly like a system prompt (Chapter 2).

Lab M1.1 · A sequential crew essential

shellpip install crewai

crew.pyfrom crewai import Agent, Task, Crew, Process

# CrewAI uses LiteLLM under the hood; point it at Claude via the model string.
LLM = "anthropic/claude-opus-4-8"

researcher = Agent(
    role="Research Analyst",
    goal="Find accurate, current facts on the topic",
    backstory="You are meticulous and cite sources.",
    llm=LLM,
)
writer = Agent(
    role="Technical Writer",
    goal="Turn research into a clear one-page brief",
    backstory="You write plainly for busy engineers.",
    llm=LLM,
)

research = Task(
    description="Research the current state of {topic}.",
    expected_output="5 bullet points with sources.",
    agent=researcher,
)
write = Task(
    description="Write a one-page brief from the research.",
    expected_output="A markdown brief, < 300 words.",
    agent=writer,
    context=[research],           # writer sees the researcher's output
)

crew = Crew(agents=[researcher, writer], tasks=[research, write],
            process=Process.sequential)
print(crew.kickoff(inputs={"topic": "vector databases"}))

Lab M1.2 · Hierarchical (manager) process essential

The sequential crew you just built made one big assumption: that you already know the right order. Research, then write, then edit — obvious, fixed, hard-coded by you. But plenty of real jobs aren't like that. "Handle this incoming support ticket" might need a database lookup, or a refund, or an escalation, or two of those, in an order that depends on what the ticket actually says. You can't wire that pipeline in advance because deciding the pipeline is itself the hard part. That's the moment you promote someone to boss.

Think of it as the difference between a factory line and a project manager. On a line, every widget takes the same stations in the same sequence. A project manager, by contrast, looks at each job, decides who should touch it and in what order, farms out the pieces, and stitches the results back together. CrewAI's hierarchical process gives you that manager: flip one flag and the framework inserts a coordinating agent that plans the work, delegates each subtask to the right specialist, and integrates their answers — no fixed order required.

The common mistake here is reaching for the manager too early. A manager is an extra agent, which means extra LLM calls on every run just to decide who does what — pure coordination overhead you pay whether or not the routing was actually ambiguous. For a fixed research→write→check flow that overhead buys you nothing; sequential is cheaper and equally good. And a second, subtler trap: people give the manager a weak, cheap model to save money, then wonder why the crew is confused. The manager does the hardest thinking in the whole system — decomposition, delegation, integration — so starving it produces a muddled team no matter how strong the workers are. Reach for hierarchical only when order is a genuine decision, and when you do, spend on the manager.

Switch the process to hierarchical and CrewAI adds a manager agent that decides which worker handles what, in what order — the supervisor topology from L1, built in.

hierarchical.pycrew = Crew(
    agents=[researcher, writer, fact_checker],
    tasks=[research, write, check],
    process=Process.hierarchical,
    manager_llm="anthropic/claude-opus-4-8",   # the manager needs its own capable model
)
result = crew.kickoff(inputs={"topic": "GraphRAG"})

Giving agents tools intermediate

An agent without tools is a very well-read colleague who never leaves the room. It can reason, summarize, and speculate from what it already knows — but it can't look anything up, can't check today's numbers, can't touch your systems. For a lot of real work that's a dealbreaker: your researcher agent is only as good as its ability to actually search your docs, not merely guess at what they might say. Tools are how you let an agent act on the world instead of only talking about it.

The mental model is refreshingly plain: a tool is just a normal Python function the agent is allowed to call. You write the function, label it with a short description of when to use it, and add it to the agent's tools list. From then on, mid-task, the agent can decide on its own to call it — search the knowledge base, hit an API, run a calculation — read the result, and keep going. The description you write is not decoration: it's the entire basis on which the agent picks the right tool, so a vague label ("does stuff") is how you get an agent that reaches for the wrong function at the wrong time.

The multi-agent-specific discipline is to scope tools tightly to each role. A tempting shortcut is to hand every agent every tool "just in case" — but that's the opposite of what a real team does. Your researcher needs search; it has no business holding a delete-database tool. Giving each specialist only the tools its job requires is least-privilege thinking (Exercise 4 makes it concrete), and it matters more in a crew than for a lone agent because there are now several actors, each an opportunity for an over-powered tool to be misused. Everything you learned about robust single-agent tooling in L3 — clear descriptions, returning errors instead of raising, gating anything destructive — applies unchanged to each agent inside the crew. A crew really is just several tool-using agents coordinating.

Agents are far more useful when they can act. CrewAI agents take a tools list — search, scraping, your own functions, or your L2/L3 retriever wrapped as a tool.

Requires: pip install crewai

tools.pyfrom crewai.tools import tool

@tool("Search internal docs")
def search_docs(query: str) -> str:
    """Search the internal knowledge base. Use for company-specific questions."""
    return retriever.invoke(query)      # your RAG retriever from L2 / Ch 3

researcher = Agent(role="Research Analyst", goal="...", backstory="...",
                   llm=LLM, tools=[search_docs])

Crews vs Flows intermediate

There's a question every orchestration tool eventually forces on you: how much do you trust the agents to figure it out themselves? A crew is the trusting answer — you describe roles and a goal, and the agents work out the collaboration at run time. That autonomy is wonderful for open-ended work and terrible for anything you need to be exactly repeatable. If your boss asks "why did it approve that refund?" and the honest answer is "the agents decided to," you have a problem. Some workflows demand a paper trail and predictable branching, not improvisation.

That's the tension between a Crew and a Flow, and it's the same axis you've already met twice — agent vs workflow in L1, chain vs graph in L4. A crew optimizes for fast, readable, autonomous teamwork. A Flow (CrewAI's event-driven, code-first layer) optimizes for the opposite: you spell out the control flow explicitly — this branch, then that condition, this piece of state — so the path is deterministic, auditable, and testable. Think of a crew as handing a project to a capable team, and a Flow as writing the standard operating procedure they must follow to the letter.

The mistake is treating this as a "which is better" contest — it isn't. They sit at different points on a control dial, and reaching for full deterministic control when you don't need it just makes you write a lot of plumbing an autonomous crew would have handled for free; reaching for autonomy on a safety-critical path leaves you unable to explain or reproduce what happened. The mature move most teams land on is a blend: prototype quickly as a crew to find the shape of the problem, then rebuild the safety-critical or auditable paths as a Flow (or in LangGraph, from L4/L5). Pick by how much control the specific path actually needs — no more, no less.

A Crew is autonomous — agents figure out how to collaborate. When you need deterministic control over the sequence (branches, conditionals, precise state), CrewAI offers Flows, an event-driven, code-first orchestration layer. It's the same tension you met in L1 (agent vs workflow) and L4 (chain vs graph).

The honest question: do you need a crew? intermediate

This is the section that will save you the most money and grief, so slow down here. Multi-agent systems demo beautifully — three little specialists chatting and handing off work looks like the future — and that visual appeal is exactly the trap. A crew feels like progress even when it's making the system slower, pricier, and harder to debug than the one-agent version it replaced. The single most common architecture mistake in this whole area is splitting a task across agents that a single well-equipped agent would have handled fine.

Feel the actual cost before you commit to it. Every agent you add is another round of LLM calls, more tokens on the bill, more latency stacked end to end, and — the sneaky one — more context that has to survive each hand-off intact. A three-agent crew doesn't just triple the calls; it triples the places where a fact can get dropped between the researcher and the writer, or where the manager mis-routes a subtask. Coordination is not free overhead you can wave away — it's the dominant new cost multi-agent introduces, and it grows with every role you bolt on. A lone agent has none of it.

So the right question is never "would a crew be cool?" but "does this task genuinely decompose into distinct specialties, or is it one job I'm splitting out of enthusiasm?" If one agent with the right tools can do it, use one agent — it's cheaper, simpler, and easier to reason about. Save the crew for work that truly breaks into different kinds of expertise (or into parallelizable chunks). The decision gate below walks that reasoning top to bottom; when in doubt, start with a single agent and split only when it demonstrably fails, not preemptively. Adding agents later is easy; untangling an over-engineered crew is not.

Multi-agent looks impressive and is often the wrong tool. Before splitting work across agents, apply this gate:

Common pitfalls advanced

Almost every crew that misbehaves fails in one of a small handful of ways, and the good news is they're all predictable once you've seen them. The theme running through this table is the same one from the whole chapter: a crew amplifies both the good and the bad. Sloppy instructions that a single agent might muddle through become a compounding drift as one vague hand-off feeds the next; a weak model in the wrong seat (usually the manager) poisons everything downstream; and coordination you forgot to wire — a missing context=[...] — quietly leaves an agent working blind. Read the fixes below as the flip side of the design advice you've already met: state concrete targets, spend on the coordinator, wire the hand-offs explicitly, and don't reach for a crew (or expect determinism from one) when the task didn't call for it.

Exercises advanced

from dataclasses import dataclass

@dataclass
class Agent:
    role: str
    goal: str
    backstory: str

researcher = Agent("Senior Researcher",
                   "find and summarize the key facts",
                   "You dig up primary sources and cite them.")
writer = Agent("Tech Writer",
               "turn findings into a clear paragraph",
               "You write plainly for a general audience.")

for a in (researcher, writer):
    print(f"{a.role}: {a.goal}")

def run_sequential(tasks, context=""):
    for task in tasks:
        context = task(context)          # each task sees the prior output
        print(f"[{task.__name__}] -> {context}")
    return context

def research(ctx):  return "facts: X grew 30% in 2025"
def analyze(ctx):   return ctx + " | trend: strong growth"
def write(ctx):     return "Report: " + ctx

final = run_sequential([research, analyze, write])
print("FINAL:", final)

WORKERS = {
    "research": lambda t: f"researched: {t}",
    "code":     lambda t: f"coded: {t}",
    "write":    lambda t: f"wrote: {t}",
}
def manager(subtasks):
    # decide which worker handles each subtask, then collect
    results = {}
    for name, payload in subtasks:
        if name not in WORKERS:
            results[name] = "no worker for this skill"
        else:
            results[name] = WORKERS[name](payload)
    return results

plan = [("research", "market size"), ("write", "exec summary")]
for k, v in manager(plan).items():
    print(k, "->", v)

TOOLS = {"search": lambda q: f"results for {q}",
         "delete": lambda x: f"deleted {x}"}
ROLE_ALLOWED = {"Researcher": {"search"}, "Admin": {"search", "delete"}}

def use_tool(role, tool, arg):
    if tool not in ROLE_ALLOWED.get(role, set()):
        return f"DENIED: {role} may not use '{tool}'"
    return TOOLS[tool](arg)

print(use_tool("Researcher", "search", "vLLM"))    # allowed
print(use_tool("Researcher", "delete", "prod-db")) # denied
print(use_tool("Admin", "delete", "temp"))          # allowed

def need_crew(distinct_specialties, steps_parallelizable, one_prompt_would_do):
    if one_prompt_would_do:
        return "single agent (or just a prompt) -- a crew is overkill"
    if distinct_specialties >= 2 or steps_parallelizable:
        return "crew -- distinct roles or parallel work justify the coordination"
    return "single agent -- one role, sequential steps"

print(need_crew(1, False, True))    # overkill
print(need_crew(3, True,  False))   # crew justified
print(need_crew(1, False, False))   # single agent

from crewai import Agent, Task, Crew, Process

researcher = Agent(
    role="Senior Researcher",
    goal="Find the key facts about {topic}",
    backstory="You dig up primary sources and cite them.",
)
writer = Agent(
    role="Tech Writer",
    goal="Write a clear one-paragraph summary",
    backstory="You write plainly for a general audience.",
)

research_task = Task(
    description="Research {topic} and list the top 3 facts.",
    expected_output="A bulleted list of 3 cited facts.",
    agent=researcher,
)
write_task = Task(
    description="Turn the research into one clear paragraph.",
    expected_output="A single paragraph.",
    agent=writer,
    context=[research_task],          # write_task consumes research_task's output
)

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    process=Process.sequential,        # each task feeds the next
)
result = crew.kickoff(inputs={"topic": "local LLM serving"})
print(result)

Knowledge check check yourself