Crewai

CrewAI Expert Skill

CrewAI is a framework for role-based multi-agent orchestration. Unlike LangGraph's low-level state-machine graphs, CrewAI provides a higher abstraction: agents are defined as Roles with Goals and Backstories, crews are composed with built-in sequential or hierarchical workflows, and inter-agent delegation is built into the framework.

Core Paradigm

from crewai import Agent, Task, Crew, Process
from crewai.tools import tool

@tool("search")
def search_web(query: str) -> str:
    """Search the web for information."""
    return f"Results for: {query}"

researcher = Agent(
    role="Senior Researcher",
    goal="Find accurate information on any topic",
    backstory="Expert researcher with 10 years of experience",
    tools=[search_web],
    verbose=True,
)

writer = Agent(
    role="Technical Writer",
    goal="Write clear reports from research findings",
    backstory="Experienced technical writer",
    verbose=True,
)

research_task = Task(
    description="Research the topic thoroughly",
    expected_output="A detailed research brief",
    agent=researcher,
)

write_task = Task(
    description="Write a report based on research",
    expected_output="A well-structured report",
    agent=writer,
)

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

result = crew.kickoff()

Core Principles

1. Agents are Roles, not functions. Role + Goal + Backstory defines the agent's identity. Strong role definitions reduce hallucination.
2. Tasks declare what, not how. Description + expected_output defines the task. The agent figures out execution.
3. Sequential is for pipelines, Hierarchical is for complexity. Sequential runs tasks in order. Hierarchical uses a manager agent to delegate and validate.
4. Manager LLM is required for Hierarchical. Without manager_llm, hierarchical process fails silently.
5. Delegation loops are real. allow_delegation=True without max_iter bounds can cause infinite handoffs.
6. Tool errors don't raise. A failed tool call marks the task as failed but doesn't raise an exception. Check task output.

Where to Start

Quick Reference

Framework Routing Guide

Reference Files

Templates

Troubleshooting

When NOT to Use CrewAI

• Single-agent task — too much abstraction for one agent
• Need fine-grained graph control (cycles, conditional branching) — use LangGraph
• Need conversational agent interactions — use AutoGen
• Need simple chain composition — use LangChain LCEL