CrewAI in Practice: A Lego-Style Framework for Multi-Agent Collaboration
The crewAIInc/crewAI repo on GitHub, with 57k stars, takes an interesting approach. It skips state machines and conversation philosophy, instead boiling multi-agent collaboration down to three concepts: Agent (an LLM call with a persona), Task (a unit of work with dependencies), and Crew (the team). A Process parameter decides execution mode. Working with the framework feels closer to writing a config file than programming.
The Problem It Solves
Single agents hit three walls on long-chained tasks:
- Context window blowout: pipelines like research → analysis → writing crammed into one prompt will eat your token budget.
- Planning collapse: LLMs skip steps when asked to decompose complex tasks on their own.
- Tool chaos: mixing search, compute, and file operations leads to brittle failure modes.
AutoGen leans conversational—agents advance through chat history, with coarse-grained control. LangGraph offers graph-based flexibility but requires you to design state machines up front. CrewAI takes the middle path: role-based agents plus a task chain, runnable from Python or YAML declarations. The essence is downgrading multi-agent collaboration from "writing a state machine" to "writing a YAML config."
How to Use It
Run pip install crewai and grab an API key from OpenAI or Anthropic. The minimal example below defines a Researcher and a Writer, chained together to produce a blog post:
from crewai import Agent, Task, Crew, Process
from crewai_tools import SerperDevTool
import os
os.environ["OPENAI_API_KEY"] = "your-key"
os.environ["SERPER_API_KEY"] = "your-serper-key"
search_tool = SerperDevTool()
researcher = Agent(
role="研究员",
goal="搜集某主题的最新行业数据",
backstory="你是一名资深行业分析师,擅长从公开资料中提炼关键数字",
tools=[search_tool],
verbose=True
)
writer = Agent(
role="撰稿人",
goal="把数据写成 500 字短报告",
backstory="你是一名科技媒体编辑,文风简洁、结论先行",
verbose=True
)
task1 = Task(
description="搜索 2024 年中国 AI Agent 行业的融资数据",
expected_output="5 条关键融资事件,每条含公司名、金额、投资方",
agent=researcher
)
task2 = Task(
description="基于上面的数据,写一篇 500 字的行业短评",
expected_output="中文短评,结构清晰,含数据引用",
agent=writer,
context=[task1]
)
crew = Crew(
agents=[researcher, writer],
tasks=[task1, task2],
process=Process.sequential
)
result = crew.kickoff()
print(result)
At runtime, the Researcher fires the search tool first, then hands results to the Writer. The line context=[task1] is the key: upstream task output flows automatically into the downstream agent's context—no manual plumbing needed. The whole flow runs in 32 lines of Python.
How It Works Under the Hood
The core abstraction has four layers:
1. Agent: role + goal + backstory + tools + llm—an LLM call unit with a persona. The backstory isn't decoration; it gets injected into the system prompt and shapes the agent's behavior.
2. Task: description + expected_output + agent + context. The context field is a list of upstream task dependencies; their outputs get injected into the current task's prompt. Task results propagate through this field automatically.
3. Crew: bundles agents and tasks together with a Process determining execution.
4. Process: three modes—
sequential: runs in order, the most common choice.hierarchical: dynamically spawns a Manager Agent for delegation, effectively building in a supervisor/executor two-layer structure.async: triggers tasks in parallel or asynchronously.
The hierarchical mode deserves a deeper look. At startup, it dynamically spawns a Manager LLM that decides which task goes to which agent and when. CrewAI essentially bakes "project management" logic into the framework—you skip writing the scheduler yourself and just flip a switch. The cost is real though: an extra LLM call can nearly double token consumption. Skip it for small tasks.
Strengths and Weaknesses
What works:
- YAML + Python dual declaration, friendly to anyone who doesn't want to design state machines.
- 57k stars, active community, responsive issue triage.
- Hierarchical mode is ready out of the box, saving you from writing your own dispatch logic.
What doesn't:
- Adapting non-mainstream LLMs (e.g., Chinese models) requires custom LLM wrappers—the official docs are thin here.
- Long task chains are opaque in debugging; tracing context flow is painful.
- Compared to LangGraph, graph-based control and conditional branching are weaker; complex business logic gets squeezed into the three Process modes.
- Tool calling is supported, but function-calling error handling feels rough.
Side-by-side: LangGraph is flexible but demands graph design; AutoGen is conversational but lacks task boundaries; CrewAI sits between them with a Lego-like feel for prototyping—but the ceiling is lower.
My Test Run
I ran a three-agent scenario: Researcher searches → Analyst structures data → Writer drafts a report, using sequential mode with gpt-4o-mini throughout.
Measured numbers:
- Time to first output: about 12 seconds (including 3 LLM calls)
- Total token usage: roughly 4,500 tokens (excluding tool calls)
- Code volume: 32 lines of Python
Compared to a single-agent prompt that just asks it to "search, analyze, and report": the single-agent version is only 8 lines of code, but output quality drops noticeably—the analysis step gets skipped, and the writer mangles the numbers. Multi-agent isolation pays for itself in quality, assuming the LLM is strong enough.
Gotchas I hit:
- Hierarchical mode's Manager Agent adds an extra LLM call, nearly doubling token cost.
verbose=Truelogs are noisy by default; turn it off in production.- CrewAI's retry on tool-call failure is weak—wrap a fault-tolerance layer around it yourself.
Who Should Use It
Good fit for:
- Teams that need to spin up a multi-agent demo or POC quickly.
- Workflows that naturally follow a division-of-labor pattern (research → analysis → writing, requirements → dev → test).
- Engineers who don't want to build state machines and context management from scratch.
Not a fit for:
- Complex logic requiring fine-grained conditional branching and loops (use LangGraph).
- Cost-sensitive high-frequency call scenarios (multi-agent = multi-LLM calls).
- Projects built primarily on non-mainstream LLMs (unless you're willing to write custom adapter layers).
- Production-grade long-chain tasks (debugging and observability aren't strong enough).
CrewAI's positioning is clear: it lowers the barrier to entry for multi-agent work as far as possible. It's not the most powerful framework, but it's likely the one you'll have running in 30 minutes. If your scenario is "a few agents splitting a job," it's worth a shot. If your scenario is "complex conditional branching plus state management," go with LangGraph.
Reference: crewAIInc/crewAI - GitHub