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
- Agents are Roles, not functions. Role + Goal + Backstory defines the agent's identity. Strong role definitions reduce hallucination.
- Tasks declare what, not how. Description + expected_output defines the task. The agent figures out execution.
- Sequential is for pipelines, Hierarchical is for complexity. Sequential runs tasks in order. Hierarchical uses a manager agent to delegate and validate.
- Manager LLM is required for Hierarchical. Without
manager_llm, hierarchical process fails silently.
- Delegation loops are real.
allow_delegation=True without max_iter bounds can cause infinite handoffs.
- 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
| You already have... |
Start here |
| Nothing — exploring CrewAI |
Sequential crew with 2 agents (research → write) |
| Agents you want to coordinate |
Build a Hierarchical crew with manager_llm |
| Tools you want to integrate |
Use @tool decorator, add tools to relevant agents |
| A production deployment |
Add callbacks, memory, error handling |
Quick Reference
| Task |
Approach |
Reference |
| Define agent |
Agent(role, goal, backstory) |
references/agent-design.md |
| Define task |
Task(description, expected_output, agent) |
references/task-design.md |
| Sequential crew |
Crew(process=Process.sequential) |
references/crew-patterns.md |
| Hierarchical crew |
Crew(process=Process.hierarchical, manager_llm=...) |
references/crew-patterns.md |
| Create tool |
@tool("name") decorator |
references/tool-integration.md |
| Add callbacks |
step_callback=fn on Agent |
references/callbacks.md |
| Enable memory |
memory=True on Crew or Agent |
references/crew-patterns.md |
Framework Routing Guide
| Scenario |
Reach for |
Why |
| Role-based multi-agent teams |
CrewAI |
Role/Goal/Backstory is the native abstraction |
| State-machine multi-agent |
LangGraph |
Graph topology, subgraphs, human-in-the-loop |
| Conversational multi-agent |
AutoGen |
Agent chat as orchestration primitive |
| Chain/agent composition |
LangChain |
LCEL pipe operator for general chains |
| Documents to query / RAG |
LlamaIndex |
Data ingestion is the primary primitive |
Reference Files
| Reference |
Load when |
File |
| Agent Design |
Defining agents with roles, goals, backstories |
references/agent-design.md |
| Task Design |
Creating tasks with descriptions and outputs |
references/task-design.md |
| Crew Patterns |
Sequential, hierarchical, consensual crews |
references/crew-patterns.md |
| Tool Integration |
Creating tools with @tool decorator |
references/tool-integration.md |
| Callbacks |
Monitoring agent and task execution |
references/callbacks.md |
| Memory System |
Unified Memory class, cross-agent context |
references/memory-system.md |
| Flows |
Event-driven orchestration connecting crews |
references/flows.md |
| FAQ & Troubleshooting |
Common errors and fixes |
references/faq-and-troubleshooting.md |
Templates
| Template |
When to use |
File |
| Research Crew |
Sequential: researcher → writer → reviewer |
templates/research-crew.py |
| Hierarchical Crew |
Manager with specialist agents |
templates/hierarchical-crew.py |
| Customer Support |
Triage → specialist → response |
templates/support-crew.py |
Troubleshooting
| Symptom |
Likely cause |
Fix |
Reference |
| Crew runs but no output |
Agent stuck in delegation loop |
Set max_iter=15 on agent |
references/agent-design.md |
| Hierarchical crew fails |
No manager_llm set |
Add manager_llm=ChatOpenAI(model="gpt-4") |
references/crew-patterns.md |
| Task never completes |
Agent exceeds max_iter |
Increase max_iter or simplify task |
references/agent-design.md |
| Tool not being called |
Tool not added to agent |
Add tools=[my_tool] to Agent definition |
references/tool-integration.md |
| High token usage |
Hierarchical mode |
Manager processes all outputs — use cheaper LLM |
references/crew-patterns.md |
| Memory between tasks not working |
Crew-level memory not set |
Add memory=True to Crew |
references/crew-patterns.md |
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
1---2name: crewai3description: >-4 Build role-based multi-agent systems with CrewAI. Agents with Role/Goal/Backstory, task5 design, crew composition (sequential or hierarchical), tool integration, callbacks, and6 production deployment. Use when orchestrating multi-agent teams or comparing agent7 frameworks. Do not use this skill for unrelated requests; route to the nearest named8 specialist.9license: MIT10metadata:11 author: Magnus Hedemark12 version: 1.1.013 source: https://skillmd.com/skills/magnus919/crewai14 upstream: https://docs.crewai.com15---1617# CrewAI Expert Skill1819CrewAI 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.2021## Core Paradigm2223```python24from crewai import Agent, Task, Crew, Process25from crewai.tools import tool2627@tool("search")28def search_web(query: str) -> str:29 """Search the web for information."""30 return f"Results for: {query}"3132researcher = Agent(33 role="Senior Researcher",34 goal="Find accurate information on any topic",35 backstory="Expert researcher with 10 years of experience",36 tools=[search_web],37 verbose=True,38)3940writer = Agent(41 role="Technical Writer",42 goal="Write clear reports from research findings",43 backstory="Experienced technical writer",44 verbose=True,45)4647research_task = Task(48 description="Research the topic thoroughly",49 expected_output="A detailed research brief",50 agent=researcher,51)5253write_task = Task(54 description="Write a report based on research",55 expected_output="A well-structured report",56 agent=writer,57)5859crew = Crew(60 agents=[researcher, writer],61 tasks=[research_task, write_task],62 process=Process.sequential,63 verbose=True,64)6566result = crew.kickoff()67```6869## Core Principles70711. **Agents are Roles, not functions.** Role + Goal + Backstory defines the agent's identity. Strong role definitions reduce hallucination.722. **Tasks declare what, not how.** Description + expected_output defines the task. The agent figures out execution.733. **Sequential is for pipelines, Hierarchical is for complexity.** Sequential runs tasks in order. Hierarchical uses a manager agent to delegate and validate.744. **Manager LLM is required for Hierarchical.** Without `manager_llm`, hierarchical process fails silently.755. **Delegation loops are real.** `allow_delegation=True` without `max_iter` bounds can cause infinite handoffs.766. **Tool errors don't raise.** A failed tool call marks the task as failed but doesn't raise an exception. Check task output.7778## Where to Start7980| You already have... | Start here |81|---|---|82| Nothing — exploring CrewAI | Sequential crew with 2 agents (research → write) |83| Agents you want to coordinate | Build a Hierarchical crew with manager_llm |84| Tools you want to integrate | Use @tool decorator, add tools to relevant agents |85| A production deployment | Add callbacks, memory, error handling |8687## Quick Reference8889| Task | Approach | Reference |90|------|----------|-----------|91| Define agent | `Agent(role, goal, backstory)` | `references/agent-design.md` |92| Define task | `Task(description, expected_output, agent)` | `references/task-design.md` |93| Sequential crew | `Crew(process=Process.sequential)` | `references/crew-patterns.md` |94| Hierarchical crew | `Crew(process=Process.hierarchical, manager_llm=...)` | `references/crew-patterns.md` |95| Create tool | `@tool("name")` decorator | `references/tool-integration.md` |96| Add callbacks | `step_callback=fn` on Agent | `references/callbacks.md` |97| Enable memory | `memory=True` on Crew or Agent | `references/crew-patterns.md` |9899## Framework Routing Guide100101| Scenario | Reach for | Why |102|----------|-----------|-----|103| Role-based multi-agent teams | **CrewAI** | Role/Goal/Backstory is the native abstraction |104| State-machine multi-agent | **LangGraph** | Graph topology, subgraphs, human-in-the-loop |105| Conversational multi-agent | **AutoGen** | Agent chat as orchestration primitive |106| Chain/agent composition | **LangChain** | LCEL pipe operator for general chains |107| Documents to query / RAG | **LlamaIndex** | Data ingestion is the primary primitive |108109## Reference Files110111| Reference | Load when | File |112|-----------|-----------|------|113| Agent Design | Defining agents with roles, goals, backstories | `references/agent-design.md` |114| Task Design | Creating tasks with descriptions and outputs | `references/task-design.md` |115| Crew Patterns | Sequential, hierarchical, consensual crews | `references/crew-patterns.md` |116| Tool Integration | Creating tools with @tool decorator | `references/tool-integration.md` |117| Callbacks | Monitoring agent and task execution | `references/callbacks.md` |118| Memory System | Unified Memory class, cross-agent context | `references/memory-system.md` |119| Flows | Event-driven orchestration connecting crews | `references/flows.md` |120| FAQ & Troubleshooting | Common errors and fixes | `references/faq-and-troubleshooting.md` |121122## Templates123124| Template | When to use | File |125|----------|-------------|------|126| Research Crew | Sequential: researcher → writer → reviewer | `templates/research-crew.py` |127| Hierarchical Crew | Manager with specialist agents | `templates/hierarchical-crew.py` |128| Customer Support | Triage → specialist → response | `templates/support-crew.py` |129130## Troubleshooting131132| Symptom | Likely cause | Fix | Reference |133|---------|-------------|-----|-----------|134| Crew runs but no output | Agent stuck in delegation loop | Set `max_iter=15` on agent | `references/agent-design.md` |135| Hierarchical crew fails | No `manager_llm` set | Add `manager_llm=ChatOpenAI(model="gpt-4")` | `references/crew-patterns.md` |136| Task never completes | Agent exceeds max_iter | Increase `max_iter` or simplify task | `references/agent-design.md` |137| Tool not being called | Tool not added to agent | Add `tools=[my_tool]` to Agent definition | `references/tool-integration.md` |138| High token usage | Hierarchical mode | Manager processes all outputs — use cheaper LLM | `references/crew-patterns.md` |139| Memory between tasks not working | Crew-level memory not set | Add `memory=True` to Crew | `references/crew-patterns.md` |140141## When NOT to Use CrewAI142143- Single-agent task — too much abstraction for one agent144- Need fine-grained graph control (cycles, conditional branching) — use LangGraph145- Need conversational agent interactions — use AutoGen146- Need simple chain composition — use LangChain LCEL