CrewAI Complete Guide: Multi-Agent Teams, Tasks, and Production Workflows (2026)

Building a single AI agent is straightforward. Building a team of specialized agents that collaborate on complex work, research, drafting, review, and delivery, requires a different abstraction. CrewAI provides that abstraction with a role-based model that mirrors how human teams actually operate.

This guide covers everything from your first two-agent crew to production deployments with custom tools, memory, hierarchical delegation, and observability. Whether you are automating content pipelines, sales research, or internal ops workflows, CrewAI gives you a pragmatic path from prototype to production.

What Is CrewAI?

CrewAI is an open-source framework for orchestrating role-playing autonomous AI agents that collaborate on tasks. Each agent has a defined role, goal, and backstory. Tasks describe specific work items with expected outputs. A Crew binds agents to tasks and defines how they execute, sequentially, in parallel, or hierarchically.

The framework sits above raw LLM APIs and below full workflow engines like Temporal. It optimizes for the common case: a small team of LLM agents with tools, passing context between steps, producing structured deliverables.

CrewAI vs. LangGraph

Aspect	CrewAI	LangGraph
Abstraction	Role-based teams	Graph nodes and edges
Learning curve	Lower for multi-agent demos	Steeper, more flexible
Control flow	Process enum (sequential, hierarchical)	Fully custom graphs
Best for	Content, research, ops automation	Complex stateful agents

Many teams use CrewAI for rapid multi-agent prototyping and migrate critical paths to LangGraph when they need fine-grained control or checkpointing.

Installation and Project Setup

pip install crewai crewai-tools
# Optional: for code execution tools
pip install crewai[tools]

Set your LLM provider via environment variables. CrewAI supports OpenAI, Anthropic, Azure, and local models through LiteLLM:

export OPENAI_API_KEY=sk-...
export CREWAI_TELEMETRY_OPT_OUT=true  # disable telemetry in production

Create a project structure that scales:

my_crew/
├── agents.py      # Agent definitions
├── tasks.py       # Task definitions
├── tools.py       # Custom tools
├── crew.py        # Crew assembly and kickoff
└── main.py        # Entry point

Defining Agents

An agent is more than a system prompt. CrewAI uses role, goal, and backstory to shape behavior:

from crewai import Agent
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o", temperature=0.2)

researcher = Agent(
    role="Senior Market Research Analyst",
    goal="Uncover actionable insights on {topic} with verified sources",
    backstory=(
        "You have 15 years of experience in competitive intelligence. "
        "You never cite unverified claims and always distinguish facts from speculation."
    ),
    llm=llm,
    verbose=True,
    allow_delegation=False,
    max_iter=15,
)

Writing Effective Backstories

Backstories are not fluff. They constrain tone, rigor, and failure modes:

• Be specific about expertise domain, not generic “you are helpful”
• Encode constraints: “You refuse to invent statistics”
• Match output format expectations: “You write in bullet points for executives”

Set allow_delegation=True only for manager agents in hierarchical processes. Individual contributors with delegation enabled tend to loop endlessly asking sub-agents for help.

Defining Tasks

Tasks specify what work gets done, who does it, and what the output should look like:

from crewai import Task

research_task = Task(
    description=(
        "Research the current state of {topic} in 2026. "
        "Cover market size, key players, and emerging trends. "
        "Cite at least 5 primary sources."
    ),
    expected_output=(
        "A markdown report with: Executive Summary, Key Findings, "
        "Competitive Landscape, and Sources sections."
    ),
    agent=researcher,
    output_file="output/research_report.md",
)

Context Chaining Between Tasks

Pass output from earlier tasks into later ones with the context parameter:

writing_task = Task(
    description="Write a blog post based on the research findings.",
    expected_output="A 1200-word blog post in markdown.",
    agent=writer,
    context=[research_task],  # writer sees research_task output
)

CrewAI injects prior task outputs into the agent’s context automatically. This is the primary mechanism for multi-step pipelines.

Assembling and Running a Crew

from crewai import Crew, Process

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

result = crew.kickoff(inputs={"topic": "enterprise RAG adoption"})
print(result.raw)

Process Types

Sequential: tasks run in order. Simplest and most predictable.

Hierarchical: a manager agent assigns and reviews work. Requires a manager_llm:

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    process=Process.hierarchical,
    manager_llm=ChatOpenAI(model="gpt-4o"),
)

Use hierarchical mode when task assignment depends on intermediate results the fixed pipeline cannot anticipate.

Custom Tools

CrewAI tools wrap Python functions with schema descriptions the LLM uses for tool selection:

from crewai.tools import BaseTool
from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description="Search query for internal docs")

class InternalSearchTool(BaseTool):
    name: str = "internal_search"
    description: str = "Search company knowledge base for technical documentation"
    args_schema: type[BaseModel] = SearchInput

    def _run(self, query: str) -> str:
        results = vector_db.similarity_search(query, k=5)
        return "\n".join(doc.page_content for doc in results)

researcher = Agent(
    role="Research Analyst",
    goal="Find accurate technical information",
    backstory="Expert researcher with access to internal docs.",
    tools=[InternalSearchTool()],
    llm=llm,
)

Install crewai-tools for prebuilt integrations: SerperDev, ScrapeWebsite, FileRead, CodeInterpreter, and more.

MCP Tool Integration

CrewAI supports Model Context Protocol servers as tool sources. Configure MCP servers in your environment and expose them to agents, the same pattern used by Claude Desktop and Cursor. This lets crews call GitHub, Slack, databases, and custom APIs through a standardized protocol.

Memory Systems

Enable crew-level memory with memory=True. CrewAI supports:

• Short-term memory: context within a single kickoff
• Long-term memory: persisted across sessions via SQLite or custom stores
• Entity memory: tracks people, companies, and concepts across runs

For production, configure a persistent storage backend rather than default SQLite in ephemeral containers:

from crewai.memory import LongTermMemory

crew = Crew(
    agents=[...],
    tasks=[...],
    memory=True,
    long_term_memory=LongTermMemory(path="/data/crew_memory.db"),
)

Memory improves continuity but increases cost and latency. Scope memory per tenant in multi-tenant SaaS deployments.

Structured Outputs

Force JSON or Pydantic-validated outputs with output_json or output_pydantic on tasks:

from pydantic import BaseModel

class CompetitorAnalysis(BaseModel):
    company: str
    market_share: str
    strengths: list[str]
    weaknesses: list[str]

analysis_task = Task(
    description="Analyze top 3 competitors for {product}.",
    expected_output="Structured competitor analysis.",
    agent=researcher,
    output_pydantic=CompetitorAnalysis,
)

Structured outputs enable downstream automation, feeding CRM updates, generating charts, or triggering webhooks without fragile string parsing.

Async and Batch Execution

For I/O-bound tool calls, use async kickoff:

import asyncio

async def run():
    result = await crew.kickoff_async(inputs={"topic": "AI agents"})
    return result

asyncio.run(run())

Kickoff multiple crews in parallel with asyncio.gather for batch research across hundreds of leads, but respect LLM rate limits with semaphores.

Production Deployment

Container Deployment Pattern

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "main.py"]

Trigger crews from a task queue (Celery, RQ, or cloud functions with extended timeout). A single crew kickoff can take 2–10 minutes depending on task count and tool latency.

Cost Control

• Use smaller models (gpt-4o-mini, Claude Haiku) for research and larger models for final writing
• Enable cache=True to avoid re-running identical tool queries
• Reduce verbose=True in production, logging overhead adds up
• Limit tool result sizes before injecting into context

Testing Crews

Write evaluation harnesses with fixed inputs and expected output patterns:

def test_research_crew():
    result = crew.kickoff(inputs={"topic": "test topic"})
    assert "Executive Summary" in result.raw
    assert len(result.raw) > 500
    assert "http" in result.raw  # expects source citations

Mock tools in CI to avoid external API calls. Use recorded fixtures for integration tests.

Common Pitfalls

Vague expected_output. “A good report” produces inconsistent results. Specify sections, length, and format explicitly.

Too many agents. Start with 2–3 agents. Every additional agent adds latency, cost, and coordination failure modes.

Delegation loops. Managers with delegation enabled and no max_iter can recurse indefinitely.

Context overflow. Long research tasks blow past context windows. Summarize intermediate outputs in a dedicated task before final writing.

Ignoring output files. Use output_file for artifacts you need to retrieve programmatically after kickoff.

When to Choose CrewAI

CrewAI excels when your workflow maps naturally to a human team: researcher → writer → editor, or analyst → strategist → presenter. It is less ideal for real-time conversational agents, strict state machines, or sub-second latency requirements.

Pair CrewAI with RAG for grounded research agents and MCP for external system access. For cost planning on multi-agent builds, see our AI agent development cost guide.

Next Steps

Prototype a two-agent crew with one custom tool, then add structured outputs and memory once the core workflow is stable. Graduate to hierarchical processes only when sequential pipelines cannot handle dynamic task routing.