The CrewAI Mental Model: Roles, Tasks, and Crews
CrewAI models multi-agent work as a crew: named specialists (agents with roles) that complete tasks, under a process that decides order and coordination.
//
Search across all documentation pages
CrewAI models multi-agent work as a crew: named specialists (agents with roles) that complete tasks, under a process that decides order and coordination.
You do not start from a free-form chat loop. You declare who does what, what "done" looks like, and how results flow between steps.
Three building blocks define almost every CrewAI program.
An Agent is configured with at least:
| Field | Role in the mental model |
|---|---|
role | Job title the model internalizes ("Senior Researcher") |
goal | What success means for this specialist |
backstory | Constraints, style, and domain bias |
tools | Callable capabilities (search, files, APIs) |
llm | Model powering this agent (optional per agent) |
Agents can also bound loops (max_iter, max_execution_time), toggle delegation (allow_delegation), and attach knowledge sources.
Think of the agent as a person on the org chart, not as the whole product workflow.
A Task is not "chat until something feels done."
It has:
| Field | Role in the mental model |
|---|---|
description | Work order, often with {placeholders} filled at kickoff |
expected_output | Acceptance criteria in natural language |
agent | Owner (required in sequential flows; manager assigns in hierarchical) |
context | Prior task outputs to inject as inputs |
output_file / structured outputs | Optional persistence or schema |
Tasks are the tickets.
If you cannot write expected_output, the crew cannot converge reliably.
A Crew owns:
process (sequential by default, or hierarchical)memory, knowledge_sources, verbose, max_rpm, callbacks, planning, streaming, checkpointsExecution starts with crew.kickoff(inputs={...}) (or async variants).
The result is a CrewOutput with raw text, optional structured forms, per-task outputs, and token usage.
from crewai import Agent, Task, Crew, Process
researcher = Agent(role="Researcher", goal="Find facts", backstory="Careful, cites sources.")
writer = Agent(role="Writer", goal="Draft clearly", backstory="Turns notes into prose.")
t1 = Task(description="Research {topic}", expected_output="Bullet notes", agent=researcher)
t2 = Task(description="Write a brief", expected_output="Markdown brief", agent=writer, context=[t1])
crew = Crew(agents=[researcher, writer], tasks=[t1, t2], process=Process.sequential)
result = crew.kickoff(inputs={"topic": "agent evals"})That sketch is the whole mental model in miniature: roles, tasks, crew, kickoff.
{topic}-style placeholders in roles and tasks at kickoff.context.Sequential process is a pipeline: task N often depends on task N-1. Hierarchical process is a managed team: a manager LLM or custom manager agent plans, delegates, and validates rather than assuming a fixed owner for every ticket.
A single system prompt that says "be a researcher and a writer" mixes incentives. CrewAI forces a split:
That split is the product feature. The framework is just the host for those contracts.
| Surface | How it fits |
|---|---|
| Tools | Skills the agent can invoke while working a task |
| Knowledge | Reference library injected for retrieval-grounded answers |
| Memory | Cross-run or cross-task recall of facts and decisions |
| Planning | Optional pre-pass that annotates tasks before execution |
| Flows | Higher-level orchestration when you need evented multi-crew graphs or chat turns |
Crews are the multi-agent team abstraction. Flows are the workflow abstraction when the product is more than one kickoff.
| Approach | Strength | Cost / risk |
|---|---|---|
| One agent, one task | Simple, cheap | Poor when skills conflict |
| Sequential multi-agent crew | Clear handoffs, easy logs | Rigid if order should change mid-run |
| Hierarchical crew | Dynamic delegation, review loop | Extra manager tokens; needs manager_llm or manager_agent |
| Crew inside a Flow | Product-grade state, chat, HITL | More moving parts than a tutorial crew |
Prefer sequential until roles truly need dynamic assignment or manager review. Prefer fewer agents with sharp tools over many agents that all share the same kitchen-sink toolbelt.
expected_output do most of the work.context is optional decoration." Without it (or careful ordering), later agents re-invent earlier work or ignore it.One agent and one task inside a crew can work, but the mental model shines at two or more specialists with a handoff.
No. Code-defined agents and tasks are valid. JSONC/YAML projects help larger teams keep config out of Python.
LangGraph centers on explicit state graphs and edges. CrewAI centers on role/task/crew collaboration patterns with process strategies built in.
{topic} placeholders?Keys in crew.kickoff(inputs={...}) (and project input defaults) interpolate into agent and task strings.
CrewOutput.raw reflects the crew's primary completion path (typically the last task's output in sequential runs). Inspect tasks_output for intermediate artifacts.
allow_delegation be true?When a worker may legitimately reassign sub-work to peers. Default false keeps ownership clear.
Attach only the tools that role needs. Shared mega-tool lists erase the specialist advantage.
On agents (max_iter, timeouts, retries) and at the product host (budget, wall clock). Do not rely on prompts alone.
Yes. One specialist can own multiple tickets in sequence.
Optional pre-iteration planning that rewrites or annotates task descriptions before agents execute them.
Turn on verbose, inspect each TaskOutput, tighten expected_output, and reduce tools before adding agents.
No. Memory is a shared notebook agents consult; roles and tasks still define the work.
Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana
@solana/web3.js+@solana/spl-token.
Reviewed by Chris St. John·Last updated Jul 16, 2026