CrewAI Tutorial: Multi-Agent Teams With Crews and Flows

The CrewAI mental model

CrewAI is an open source Python framework for orchestrating role playing AI agents, released under the MIT licence according to its PyPI listing. Its documentation describes two main parts. Crews are teams of autonomous agents with specific roles, goals and tools that collaborate on tasks. Flows are event driven workflows that manage state and control execution, including conditionals, loops and branching. A Flow can trigger a Crew.

The vocabulary maps closely to how people already organise work. You define agents the way you would describe colleagues, with a role, a goal and a backstory. You define tasks with a description and the output you expect. Then you assemble them into a crew and start it. This makes CrewAI easy to explain to a product manager or a client, which is part of its appeal.

Because agents are described in natural language, the quality of a crew depends heavily on how precisely you write roles, goals and expected outputs. Vague goals such as do research produce vague work. Specific goals such as list five Indian cold chain operators with their founding year and a source link produce output you can check. Treat these fields as part of your code, review them in pull requests and keep them under version control.

Agents, tasks and a sequential crew

The example follows the crews page of the CrewAI documentation. A researcher agent gathers facts and a writer agent turns them into a short brief. Each task names the agent that owns it and states the expected output, which acts as a definition of done. With Process.sequential, the tasks run in order and the output of the first is available to the second.

To run it you need CrewAI installed and a model configured, which the installation page of the docs covers. The kickoff call runs the whole crew and returns the final result, which you can print or save. In a real project you would give the researcher tools, for example a search tool, and keep the writer tool free so it can only work with what it is given. That separation makes errors easier to trace.

# Illustrative, check the official docs for the current API
# Based on docs.crewai.com/en/concepts/crews
from crewai import Agent, Crew, Task, Process

researcher = Agent(
    role="Market researcher",
    goal="Find key facts about cold chain logistics demand in India",
    backstory="A careful analyst who relies on clear evidence.",
)
writer = Agent(
    role="Writer",
    goal="Summarise research into a short brief",
    backstory="A concise writer who turns notes into plain language.",
)
research_task = Task(
    description="Research recent cold chain logistics demand in India.",
    expected_output="A bullet list of key findings with sources.",
    agent=researcher,
)
write_task = Task(
    description="Write a short brief from the research findings.",
    expected_output="A one paragraph brief.",
    agent=writer,
)
crew = Crew(agents=[researcher, writer], tasks=[research_task, write_task],
            process=Process.sequential)
print(crew.kickoff())

Hierarchical processes, memory and planning

Sequential is the default process. CrewAI also supports a hierarchical process, where a manager agent delegates work and checks results; it requires either a manager_llm or a manager_agent. Hierarchical crews feel closer to a real team, but every delegation adds model calls, time and cost, and the manager can make poor routing choices. Start sequential and move to hierarchical only when you can show that dynamic delegation improves results on your test cases.

Crews have other switches worth knowing. The memory attribute stores execution memories, including short term, long term and entity memory. The planning attribute asks a planner to create a plan from the crew data before each run and adds it to the task descriptions. The verbose attribute controls logging and defaults to False. Turn verbose on while developing so you can read each agent's reasoning.

When a team of agents helps, and when it hurts

Multiple agents help when the work has genuinely different skills or permissions. A proposal generator for an IT services firm might use one agent that reads the client's RFP, one that drafts a technical approach and one that checks the pricing section against a rate card. Separating them lets you give each a focused prompt and only the tools it needs, which also limits the damage if one is misled by untrusted input.

Multiple agents hurt when they are a costume for one task. If three agents simply pass text along a chain, a single agent with a good prompt is usually cheaper and easier to debug. Use Flows for the parts that must be deterministic, such as fetching the RFP and saving the final file, and keep crews for the parts that need judgement. XDQ Labs teams treat each extra agent as a cost that must earn its place in an evaluation run.

• Use a crew when roles need different tools or permissions.
• Use a Flow for fixed steps, state and branching logic.
• Measure quality and cost before adding a manager agent.

Check your understanding