CrewAI Tutorial — Role-Based Multi-Agent Teams & Orchestration

01 The Core Triad: Agent, Task, and Crew

Primitives

👤

Agent

A specialized worker defined by a role, a measurable goal, and a detailed backstory that primes its tone, domain expertise, and prompt behavior. Equipped with tools and optional delegation power.

📋

Task

An actionable unit of work assigned to an Agent with a description and an explicit expected_output format (Markdown, JSON, Pydantic). Tasks can execute synchronously or asynchronously.

👥

Crew

The container that orchestrates the execution flow between Agents and Tasks. Handles shared memory, manager LLM delegation, tool execution tracking, and final synthesis.

02 Sequential vs Hierarchical Processes

Execution Flow

➡️

Process.sequential

Linear Assembly Line

Tasks are executed in exact list order. The output of Task 1 is automatically passed as context into Task 2, and so on.

from crewai import Crew, Process

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

Best for: Predictable pipelines like News Gathering → Content Drafting → Proofreading.

👑

Process.hierarchical

Manager LLM Delegation

A designated manager_llm or manager_agent analyzes the overall goals, dynamically assigns tasks to workers, reviews outputs, and re-delegates if quality standards are not met.

from crewai import Crew, Process
from langchain_openai import ChatOpenAI

crew = Crew(
    agents=[engineer, qa_analyst, security_auditor],
    tasks=[build_feature, verify_security],
    process=Process.hierarchical,
    manager_llm=ChatOpenAI(model="gpt-6-sol"),
    verbose=True
)

Best for: Complex exploratory projects where steps depend on intermediary findings.

03 CrewAI Multi-Tier Memory System

State & Context

When enabled with memory=True, CrewAI maintains three distinct memory layers simultaneously:

Short-Term Memory

Uses Chroma vector search to store intermediate execution context and agent thoughts during the active crew run. Agents can query past tool findings semantically.

Long-Term Memory

Persists task outcomes and reflections across separate crew runs in a local SQLite database (~/.crewai/memory/), allowing agents to learn from past executions over weeks.

Entity Memory

Extracts key subjects, organizations, people, and concepts into structured entity cards so agents maintain factual consistency across all conversation turns.

04 Custom Tool Integration with CrewAI

Extensibility

You can write custom tools either using the @tool decorator for lightweight functions or subclassing BaseTool with a Pydantic schema for robust validation:

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

class StockQuerySchema(BaseModel):
    ticker: str = Field(..., description="The stock ticker symbol, e.g. NVDA, AAPL")

@tool("Stock Price Lookup", args_schema=StockQuerySchema)
def fetch_stock_price(ticker: str) -> str:
    """Fetch current stock price and P/E ratio for a given ticker."""
    # Simulated internal market API call
    return f"{ticker.upper()} Price: $128.50, P/E: 42.1 (Real-Time API)"

Production Multi-Agent Competitive Intelligence Crew

A complete runnable CrewAI script with specialized personas, sequential tasks, and markdown output.

CrewAI 0.80+

import os
from crewai import Agent, Task, Crew, Process
from crewai.tools import tool
from langchain_openai import ChatOpenAI

# 1. Initialize LLM
llm = ChatOpenAI(model="gpt-6-sol", temperature=0.2)

# 2. Define Custom Search Tool
@tool("Market Intelligence Search")
def market_search(query: str) -> str:
    """Simulated enterprise market intelligence search."""
    return f"Latest data for '{query}': Enterprise adoption of agentic AI up 320% year-over-year in 2025."

# 3. Create Agents with Distinct Personas
senior_researcher = Agent(
    role="Lead AI Market Analyst",
    goal="Uncover cutting-edge developments in autonomous multi-agent infrastructure",
    backstory="You are a veteran Wall Street tech analyst known for uncovering underlying architecture trends before they become mainstream.",
    tools=[market_search],
    llm=llm,
    verbose=True
)

chief_editor = Agent(
    role="Principal Technical Writer",
    goal="Synthesize raw market data into an executive-ready strategic briefing",
    backstory="You are a former senior editor at IEEE Software who excels at translating complex technical benchmarks into actionable executive summaries.",
    llm=llm,
    verbose=True
)

# 4. Define Tasks with Clear Expected Outputs
research_task = Task(
    description="Analyze current adoption and enterprise architectural shifts toward multi-agent frameworks.",
    expected_output="A bulleted summary of the top 3 architectural findings with supporting statistics.",
    agent=senior_researcher
)

synthesis_task = Task(
    description="Using the findings from the research task, draft a concise 2-paragraph executive briefing for the CTO.",
    expected_output="A polished 2-paragraph Markdown briefing ready for executive distribution.",
    agent=chief_editor,
    output_file="briefing.md"
)

# 5. Form the Crew and Kickoff
crew = Crew(
    agents=[senior_researcher, chief_editor],
    tasks=[research_task, synthesis_task],
    process=Process.sequential,
    memory=True,
    verbose=True
)

result = crew.kickoff(inputs={"industry": "Autonomous AI Agents"})
print("\n--- FINAL DELIVERABLE ---\n")
print(result)

06 When to Choose CrewAI vs Other Frameworks

Criteria	CrewAI	LangGraph	AutoGen
Philosophy	Role-playing department team	Cyclic state machine graph	Conversational group chat
Setup Complexity	Very Low (Declarative Python)	Medium (Nodes, Edges, Reducers)	Medium-High
Dynamic Delegation	Built-in (Hierarchical manager)	Manual (Supervisor node)	Built-in (GroupChatManager)
State Control	Implicit task context passing	Explicit typed dictionary state	Chat history messages

07 Frequently Asked Questions

Can I run CrewAI with local open-source models (e.g. Ollama, vLLM)? →

Yes! CrewAI works with any OpenAI-compatible API or LangChain LLM wrapper. You can configure agents with Ollama using ChatOllama(model="llama3.3") or setting OPENAI_API_BASE="http://localhost:11434/v1".

How do I avoid runaway loops and excessive token costs? →

Always configure max_iter=15 and max_rpm=30 on your Agent instances. You can also specify cache=True on tool calls to prevent repeating identical web searches or database queries.

Can human feedback be inserted into a CrewAI workflow? →

Yes. Setting human_input=True on a Task prompts the human operator in the terminal (or via a custom handler) to review the agent's draft and provide feedback before the crew advances to the next task.

Role-Based Agent Teams with CrewAI