CrewAI — role-based agent teams

Setup#

pip install crewai

Written against crewai 1.15. Be warned about the size: the install pulls in a vector database, Apache Arrow and an ONNX runtime, among others — several hundred megabytes of dependencies. On the first run, CrewAI prints a one-time question about enabling tracing; answering no saves that preference. It also sends anonymous usage telemetry, which you can switch off by setting the environment variable CREWAI_DISABLE_TELEMETRY=true.

CrewAI normally drives a hosted model (via an API key) or a local one through Ollama. For a lesson, both would make the output depend on your machine and your key. Instead, the example below plugs in a scripted model, which CrewAI supports through its BaseLLM class — so it runs offline, free, and prints the same thing for everyone. The crew mechanics are identical either way.

A two-agent crew you can run#

from crewai import Agent, Task, Crew, Process, BaseLLM

# a scripted model, so this runs offline and costs nothing.
# CrewAI accepts any subclass of BaseLLM that implements call().
class ScriptedLLM(BaseLLM):
    replies: list[str] = []
    calls: int = 0

    def call(self, messages, tools=None, callbacks=None,
             available_functions=None, from_task=None, from_agent=None,
             response_model=None):
        reply = self.replies[min(self.calls, len(self.replies) - 1)]
        self.calls += 1
        return reply

llm = ScriptedLLM(model="scripted", replies=[
    "Plan: revise probability basics, then attempt ten past-paper questions.",
    "Checked: the plan fits in two hours if each question gets ten minutes.",
])

planner = Agent(
    role="Study planner",
    goal="Turn a vague study wish into a concrete plan",
    backstory="You plan revision sessions for busy students.",
    llm=llm,
)
checker = Agent(
    role="Plan checker",
    goal="Verify a study plan fits the available time",
    backstory="You are strict about realistic time budgets.",
    llm=llm,
)

plan = Task(
    description="Make a two-hour study plan for probability.",
    expected_output="A short, concrete plan.",
    agent=planner,
)
check = Task(
    description="Check the plan fits in two hours.",
    expected_output="A one-line verdict.",
    agent=checker,
)

crew = Crew(agents=[planner, checker], tasks=[plan, check],
            process=Process.sequential)

result = crew.kickoff()
for t in result.tasks_output:
    print(f"[{t.agent}]")
    print(t.raw)
print("final answer:", result.raw)

[Study planner]
Plan: revise probability basics, then attempt ten past-paper questions.
[Plan checker]
Checked: the plan fits in two hours if each question gets ten minutes.
final answer: Checked: the plan fits in two hours if each question gets ten minutes.

To use a real model, delete the ScriptedLLM class and build the llm differently — for example llm = LLM(model="ollama/llama3.2", base_url="http://localhost:11434") with LLM imported from crewai, or set an API key and name a hosted model. Nothing else in the file changes.

Line by line, the parts that are not obvious#

role, goal, backstory — these are not decoration. CrewAI assembles them into the agent's system prompt. Writing them is prompt engineering wearing a nicer shirt, and vague roles produce vague agents.

expected_output — the most underrated field in the framework. It goes into the prompt as the definition of done. "A one-line verdict" gets you one line; leave it woolly and you get essays.

Process.sequential — tasks run in list order, and each task's output is appended to the context of the next. The alternative, Process.hierarchical, adds a manager model that decides who works next and reviews results — more flexible, and at least one extra model call per hand-off.

result.tasks_output — one entry per task, in order, with .raw holding the text. The crew's result.raw is the final task's output.

Why does ScriptedLLM work? CrewAI talks to models through one interface: call(messages, ...) -> str. Anything honouring that contract is a valid model, which is also how you would wire in a company-internal model gateway.

Common mistakes#

No model configured. Without an llm= and without an OPENAI_API_KEY in the environment, the crew fails at kickoff with an authentication error from the default OpenAI client. The fix is explicit: pass llm= to every agent, or set the key.

Treating expected_output as optional paperwork. It is required, and it steers the model harder than the description does. Write it like an acceptance test: "a bulleted list of exactly three ideas, one line each".

Five agents where two would do. Every agent adds calls, latency and cost, and agents that review other agents' reviews add noise, not quality. Start with two. Add a third only when you can name the failure it fixes.

Forgetting that agents share no memory by default. Task outputs flow forward, but an agent does not remember a previous kickoff. Persistent memory across runs exists in CrewAI, but it is a feature you enable deliberately, not something to assume.

Try it yourself#

Add a third task, "rewrite the plan as a checklist", owned by a new formatter agent, and extend the scripted replies with a third string. Watch it appear in tasks_output. Then change expected_output on the first task to demand five bullet points and see how the prompt CrewAI builds changes — add verbose=True to the Crew to watch the prompts fly past.

What to learn next#

• AutoGen — conversational multi-agent systems — agents that talk in a group chat instead of a task line.
• LangGraph — agents as graphs — the explicit-control-flow alternative.
• Prompt engineering — the skill hiding inside every role and backstory field.