CrewAI Framework: Building Role-Based Multi-Agent Teams in Python

What Makes CrewAI Different

Most agent frameworks treat agents as isolated units that you wire together manually. CrewAI takes a different approach: it models agents as members of a crew with defined roles, goals, and backstories. Each agent is assigned tasks, and a process orchestrator determines execution order. The metaphor is a real team of specialists collaborating on a project.

This role-based design makes CrewAI particularly effective for workflows where different expertise domains need to collaborate — research and writing, analysis and review, planning and execution.

Core Concepts

CrewAI has four fundamental building blocks:

flowchart TD
    GOAL(["Crew goal"])
    MGR["Manager agent<br/>hierarchical process"]
    R1["Researcher agent<br/>role plus backstory"]
    R2["Analyst agent"]
    W1["Writer agent"]
    T1["Task A<br/>research"]
    T2["Task B<br/>analyze"]
    T3["Task C<br/>draft"]
    TOOLS[("Tools<br/>web search, files")]
    OUT(["Crew output"])
    GOAL --> MGR
    MGR --> T1 --> R1 --> TOOLS
    R1 --> T2 --> R2
    R2 --> T3 --> W1 --> OUT
    style MGR fill:#4f46e5,stroke:#4338ca,color:#fff
    style TOOLS fill:#ede9fe,stroke:#7c3aed,color:#1e1b4b
    style OUT fill:#059669,stroke:#047857,color:#fff

Agents represent individual team members. Each agent has a role (what they do), a goal (what they aim to achieve), and a backstory (context that shapes their behavior). These are not just labels — they are injected into the system prompt and meaningfully affect how the LLM reasons.

Tasks are units of work assigned to agents. Each task has a description, an expected output format, and an assigned agent. Tasks can depend on the output of other tasks.

Crews are the orchestration layer. A crew brings together agents and tasks, defines the process type, and manages execution.

Processes control how tasks execute. CrewAI supports sequential (one after another), hierarchical (a manager delegates to workers), and custom processes.

Building a Research Crew

Here is a practical example: a crew that researches a topic and writes a report.

from crewai import Agent, Task, Crew, Process
from crewai_tools import SerperDevTool

# Tools
search_tool = SerperDevTool()

# Define agents with distinct roles
researcher = Agent(
    role="Senior Research Analyst",
    goal="Find comprehensive, accurate information on the given topic",
    backstory="""You are an experienced research analyst who specializes
    in technology trends. You are thorough and always verify claims
    from multiple sources.""",
    tools=[search_tool],
    verbose=True,
    allow_delegation=False,
)

writer = Agent(
    role="Technical Content Writer",
    goal="Write clear, engaging content based on research findings",
    backstory="""You are a skilled technical writer who transforms
    complex research into accessible content. You focus on accuracy
    and clarity.""",
    verbose=True,
    allow_delegation=False,
)

editor = Agent(
    role="Editorial Reviewer",
    goal="Ensure content is factually accurate, well-structured, and polished",
    backstory="""You are a meticulous editor with a background in
    technical publishing. You catch errors others miss and improve
    readability without changing the author's voice.""",
    verbose=True,
    allow_delegation=False,
)

Now define the tasks and wire them into a crew:

# Define tasks with dependencies
research_task = Task(
    description="""Research the topic: {topic}
    Find key facts, recent developments, and expert opinions.
    Include specific data points and sources.""",
    expected_output="A detailed research brief with cited sources",
    agent=researcher,
)

writing_task = Task(
    description="""Using the research brief, write a 1000-word article.
    Structure it with an introduction, 3-4 main sections, and a conclusion.
    Make it accessible to a technical audience.""",
    expected_output="A polished 1000-word article in markdown format",
    agent=writer,
    context=[research_task],  # Depends on research output
)

editing_task = Task(
    description="""Review and edit the article for accuracy, clarity,
    and readability. Fix any factual errors, improve transitions,
    and ensure consistent tone.""",
    expected_output="The final edited article ready for publication",
    agent=editor,
    context=[writing_task],  # Depends on writing output
)

# Assemble the crew
crew = Crew(
    agents=[researcher, writer, editor],
    tasks=[research_task, writing_task, editing_task],
    process=Process.sequential,
    verbose=True,
)

# Execute
result = crew.kickoff(inputs={"topic": "Agentic AI in Healthcare 2026"})
print(result)

Hierarchical Process

For complex workflows, the hierarchical process adds a manager agent that delegates tasks dynamically:

crew = Crew(
    agents=[researcher, writer, editor],
    tasks=[research_task, writing_task, editing_task],
    process=Process.hierarchical,
    manager_llm="gpt-4o",  # Manager uses this model
    verbose=True,
)

In hierarchical mode, the manager decides which agent handles each task, can reassign work, and synthesizes outputs. This is useful when task assignments should be dynamic rather than predetermined.

Delegation and Collaboration

When allow_delegation=True, agents can ask other crew members for help. The researcher might delegate a sub-question to the writer if it requires explaining a concept. This mimics how real teams work — specialists consult each other.

Strengths and Limitations

CrewAI excels at workflows that mirror real team collaboration. The role-based metaphor makes it intuitive to design multi-agent systems. The context parameter on tasks creates clean dependency graphs without manual state management.

The main limitation is that CrewAI adds overhead for simple single-agent tasks. If you just need one agent with tools, CrewAI's crew/task/agent ceremony is unnecessary. It shines when you genuinely need multiple perspectives on a problem.

FAQ

How does CrewAI handle errors when one agent fails?

CrewAI has built-in retry logic. If an agent's task fails, the framework retries with the same context. You can configure max_retry_limit on tasks. In hierarchical mode, the manager can reassign failed tasks to different agents.

Can CrewAI agents use different LLM providers?

Yes. Each agent can specify its own llm parameter. You could have the researcher use GPT-4o for reasoning-heavy work while the writer uses Claude for better prose. CrewAI supports any LiteLLM-compatible model.

What is the difference between sequential and hierarchical process?

Sequential executes tasks in the order you define them — predictable and debuggable. Hierarchical introduces a manager agent that dynamically assigns and delegates tasks — more flexible but harder to predict and debug.

---

#CrewAI #MultiAgentSystems #AgentFrameworks #Python #AgentOrchestration #AgenticAI #LearnAI #AIEngineering