CrewAI

CrewAI is the most popular open-source multi-agent framework. It combines Flows (stateful, event-driven workflows) with Crews (teams of role-playing agents that collaborate autonomously). Over 100,000 developers have completed CrewAI's certification courses.

A Crew is a team of agents with specific roles, goals, and tools. A Flow is the scaffolding — it manages state, handles events, and decides when to trigger a Crew. For production applications, Flows + Crews together give you structure plus intelligence.

Note:

Start with a simple Crew (agents + tasks + process). Graduate to Flows when you need persistent state, conditional routing, or event-driven triggers. Most toy examples use Crews alone — all production apps use Flows.

Installation

Install CrewAI

CrewAI requires Python 3.10+. Install via pip or uv.

pip install crewai
# or
uv pip install crewai

Configure API Keys

CrewAI uses OpenAI by default. Set your key as an environment variable.

export OPENAI_API_KEY=sk-...

For Anthropic or other providers, configure via litellm:

export ANTHROPIC_API_KEY=sk-ant-...

Verify Installation

Run a quick Crew to confirm everything is wired.

pip install crewai[tools]
crewai create my-first-crew
cd my-first-crew
crewai run

The scaffolded Crew will execute and print results.

Core Concepts

Architecture Overview

Agent

An autonomous unit with a role, goal, backstory, and tools. Agents make decisions based on their role and available tools.

Values: role, goal, backstory, tools, llm

Task

A unit of work assigned to an agent or crew. Has a description, expected output, and optional context from previous tasks.

Values: description, expected_output, agent, context

Crew

A team of agents that collaborate to complete tasks. Manages task delegation, agent coordination, and process flow.

Values: agents, tasks, process, verbose

Flow

A stateful, event-driven workflow that orchestrates Crews. Manages state across steps, handles conditional routing, and can persist data.

Values: state, steps, event triggers, persistence

Creating a Crew

This example creates a research crew with two agents — a researcher who finds information and a writer who synthesizes it.

from crewai import Agent, Task, Crew, Process

# Define agents
researcher = Agent(
    role="Senior Researcher",
    goal="Find accurate, well-sourced information on the topic",
    backstory="You are a research analyst with 15 years of experience.",
    tools=[],  # Add tools like SerperDevTool, WebsiteSearchTool
    verbose=True
)

writer = Agent(
    role="Content Writer",
    goal="Synthesize research into clear, actionable content",
    backstory="You are a technical writer who makes complex topics accessible.",
    verbose=True
)

# Define tasks
research_task = Task(
    description="Research the latest developments in AI agent frameworks.",
    expected_output="A bulleted list of 5 key developments with sources.",
    agent=researcher
)

write_task = Task(
    description="Write a 3-paragraph summary of the research findings.",
    expected_output="A well-written summary suitable for a blog post.",
    agent=writer,
    context=[research_task]  # Writer gets researcher's output
)

# Create and run the crew
crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    process=Process.sequential,
    verbose=True
)

result = crew.kickoff()
print(result)

Process Types

When to Use Each Process

Sequential

Tasks execute one after another in order. Each task receives context from the previous task. Best for pipelines where each step depends on the prior one.

Values: Process.sequential

Hierarchical

A manager agent delegates tasks to workers and validates results. Best for complex tasks where the manager needs to adapt the plan mid-execution.

Values: Process.hierarchical

Tools

CrewAI agents use tools to interact with external systems. Built-in tools cover the most common needs, and custom tools are one function away.

from crewai_tools import SerperDevTool, ScrapeWebsiteTool, FileReadTool

# Built-in tools
researcher.tools = [
    SerperDevTool(),        # Google search via Serper API
    ScrapeWebsiteTool(),    # Extract content from URLs
]

# Custom tool
from crewai import tool

@tool("calculate_roi")
def calculate_roi(investment: float, return_amount: float) -> str:
    """Calculate return on investment percentage."""
    roi = ((return_amount - investment) / investment) * 100
    return f"ROI: {roi:.1f}%"

analyst = Agent(
    role="Financial Analyst",
    goal="Analyze investment opportunities",
    tools=[calculate_roi]
)

Model Wiring

CrewAI uses OpenAI's GPT-4o by default. Switch models per-agent or globally.

import os
from crewai import LLM

# Default: reads OPENAI_API_KEY and uses gpt-4o
# No config needed

# Per-agent model
agent = Agent(
    role="Analyst",
    goal="Analyze data",
    llm="anthropic/claude-sonnet-4-20250514"  # via litellm
)

# Custom endpoint (OpenRouter, Ollama, etc.)
agent = Agent(
    role="Analyst",
    goal="Analyze data",
    llm=LLM(
        model="openai/gpt-4o",
        base_url="https://openrouter.ai/api/v1",
        api_key=os.environ["OPENROUTER_API_KEY"]
    )
)

# Run locally with Ollama
agent = Agent(
    role="Analyst",
    goal="Analyze data",
    llm=LLM(
        model="ollama/llama3.2",
        base_url="http://localhost:11434"
    )
)

Note:

Tool dependencies. Built-in tools like SerperDevTool require additional packages and API keys. Install with pip install crewai[tools] and set SERPER_API_KEY in your environment. The agent will fail silently if tools are missing API keys — enable verbose=True to debug.

Key Takeaway

CrewAI's strength is speed to a working prototype. An agent + task + crew is ~30 lines of code. For production, always use Flows — they give you state management, error handling, and conditional routing that raw Crews lack. The most common production pattern: a Flow that receives a request, triggers a Crew for the heavy lifting, validates the output, and routes to the next step.

CrewAI Setup Guide