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.