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.
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.
Summary
- CrewAI separates Agent (who acts), Task (what must be produced), and Crew (how the team runs) so multi-agent work is an explicit pipeline, not an ad hoc conversation.
- Insight: Role and task contracts make tools, prompts, and stop conditions easier to scope than one mega-agent that tries every tool on every turn.
- Key Concepts: role / goal / backstory, description / expected_output, task context, process (sequential vs hierarchical), kickoff, CrewOutput.
- When to Use: Multi-step jobs with clear handoffs (research then write, gather then analyze) where specialist prompts and tool sets differ.
- Limitations/Trade-offs: More agents cost more tokens and latency. Vague roles or overlapping tasks create thrash instead of collaboration.
- Related Topics: role authoring, process choice, tools, memory, interactive chat sessions.
Foundations
Three building blocks define almost every CrewAI program.
Agent = specialist with a job description
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.
Task = unit of work with a deliverable
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.
Crew = team + process + run knobs
A Crew owns:
- The list of agents and tasks
process(sequentialby default, orhierarchical)- Shared knobs:
memory,knowledge_sources,verbose,max_rpm, callbacks, planning, streaming, checkpoints
Execution 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.
Mechanics & Interactions
How information moves
- Inputs fill
{topic}-style placeholders in roles and tasks at kickoff. - Each task runs under its agent (or a manager-chosen agent in hierarchical mode).
- The agent may call tools, recall memory, or query knowledge sources.
- Task output becomes available to later tasks via order and/or explicit
context. - The crew returns the final task's primary result plus the full task list.
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.
Why role + task is stronger than one prompt
A single system prompt that says "be a researcher and a writer" mixes incentives. CrewAI forces a split:
- The researcher optimizes for coverage and evidence.
- The writer optimizes for structure and audience.
- Tools can be least-privilege per role (search only on researcher; file write only on writer).
That split is the product feature. The framework is just the host for those contracts.
Related surfaces that still fit the model
| 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.
Advanced Considerations
| 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.
Common Misconceptions
- "More agents always means better quality." Often it means more handoff loss and cost. Split only when goals or tools differ.
- "Role titles alone control behavior." Goal, backstory, tools, and
expected_outputdo most of the work. - "
contextis optional decoration." Without it (or careful ordering), later agents re-invent earlier work or ignore it. - "CrewAI is only for chatbots." The default mental model is batch team execution. Conversational surfaces are separate (chat CLI / conversational flows).
- "Hierarchical means I can skip task design." Managers still need well-scoped tasks and capable workers.
FAQs
What is the minimum viable crew?
One agent and one task inside a crew can work, but the mental model shines at two or more specialists with a handoff.
Do I need YAML or JSONC?
No. Code-defined agents and tasks are valid. JSONC/YAML projects help larger teams keep config out of Python.
How does this differ from LangGraph?
LangGraph centers on explicit state graphs and edges. CrewAI centers on role/task/crew collaboration patterns with process strategies built in.
What fills {topic} placeholders?
Keys in crew.kickoff(inputs={...}) (and project input defaults) interpolate into agent and task strings.
Is the final answer always the last task?
CrewOutput.raw reflects the crew's primary completion path (typically the last task's output in sequential runs). Inspect tasks_output for intermediate artifacts.
When should allow_delegation be true?
When a worker may legitimately reassign sub-work to peers. Default false keeps ownership clear.
How do tools interact with roles?
Attach only the tools that role needs. Shared mega-tool lists erase the specialist advantage.
Where do stop conditions live?
On agents (max_iter, timeouts, retries) and at the product host (budget, wall clock). Do not rely on prompts alone.
Can two tasks share one agent?
Yes. One specialist can own multiple tickets in sequence.
What is planning on a crew?
Optional pre-iteration planning that rewrites or annotates task descriptions before agents execute them.
How should I debug a bad crew?
Turn on verbose, inspect each TaskOutput, tighten expected_output, and reduce tools before adding agents.
Does memory change the mental model?
No. Memory is a shared notebook agents consult; roles and tasks still define the work.
Related
- CrewAI Basics - first Researcher + Writer crew
- Defining Agent Roles, Goals, and Backstories - writing strong role contracts
- Sequential vs Hierarchical Crew Processes - process cheatsheet
- Building a Custom Tool for a CrewAI Agent - tool recipe
- CrewAI 1.14's Pluggable Memory, Knowledge, and RAG Backends - memory and knowledge
- CrewAI Best Practices - scoping checklist
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.