Skip to Content

CrewAI (Role-Based Crews)

When to use

Spin up a ‘crew’ of role-based agents (researcher, writer, reviewer) that plan, delegate and execute a task together.

Analogy

A film crew with a director, a researcher, a writer, and an editor. The director delegates; the crew executes; the editor polishes the cut.

Data-flow diagram

   Crew(task)
     |
     +-- Agent: researcher (goal, backstory, tools)
     +-- Agent: writer
     +-- Agent: reviewer
     |
     Process: sequential / hierarchical
     |
     v
   crew.kickoff(inputs) -> final answer

Deep explanation

CrewAI organises agents into a crew around a task. Each Agent has a role, goal, backstory, and tools. A Process (sequential or hierarchical) defines execution order; Crew.kickoff starts the work. Use CrewAI when you want a stories-style orchestration where agents have clear personas and hand off work to each other.

Examples

Example 1

from crewai import Agent, Task, Crew, Process
researcher = Agent(role='Researcher', goal='Find facts about {topic}',
                   backstory='You are an investigative analyst.', allow_delegation=False)
writer     = Agent(role='Writer',     goal='Write a blog post on {topic}',
                   backstory='You turn research into prose.', allow_delegation=False)
 
task = Task(description='Write a 300-word post about {topic}', expected_output='blog post',
            agent=writer, context_from=[researcher])

Agent encapsulates role + goal + backstory; Task binds an output to an agent.

Example 2

crew = Crew(agents=[researcher, writer], tasks=[task],
            process=Process.sequential, verbose=True)
result = crew.kickoff(inputs={'topic':'vector databases'})
print(result)

Process.sequential runs tasks in order; Process.hierarchical auto-selects a manager agent.

Example 3

# tools: agent can search
from crewai_tools import SerperDevTool
researcher.tools = [SerperDevTool()]
result = crew.kickoff(inputs={'topic':'pgvector 0.8 release'})

Tools (SerperDevTool etc.) act like function-calling — the agent decides when to call.

Common mistake

Allowing delegation across all agents. CrewAI then auto-creates a manager that calls itself. Be explicit: allow_delegation=False for leaf agents.

Key takeaway

CrewAI equals Agents + Tasks + Process + Crew.kickoff. Sequential for deterministic ordering; hierarchical for dynamic delegation.

Production Failure Playbook

Failure scenario 1: delegate-storm

Failure scenario 2: tool-orphaned