CrewAI

Standalone Python multi-agent framework: role-based Crews (agents, tasks, sequential/hierarchical process) for autonomy, and event-driven Flows for deterministic state and control.

Contents

CrewAI is an open-source (MIT), standalone Python framework for multi-agent automation. It has its own primitives for agents, tasks, crews and flows and doesn’t depend on other agent frameworks. It needs Python 3.10–3.13 and uses uv for packaging (README). It has two layers. Crews are teams of role-playing agents that collaborate autonomously on tasks. Flows are event-driven Python classes that own state, ordering and branching. CrewAI’s recommended architecture is a Flow for the application, with Crews embedded in the steps that need autonomous collaboration (intro). The defining instinct is declarative: you name the roles, the tasks and the expected outputs up front (Notebook). A commercial suite, CrewAI AMP, adds managed deployment, tracing and a control plane (README).

Crews: agents, tasks, process

flowchart TD
  subgraph CREW["Crew (process = sequential | hierarchical)"]
    A1["Agent: role + goal + backstory + tools + llm"]
    A2["Agent ..."]
    T1["Task: description + expected_output (+ agent, context, output_pydantic, guardrail)"]
    T2["Task ..."]
  end
  K["crew.kickoff(inputs)"] --> CREW --> O["CrewOutput (raw / pydantic / json_dict / tasks_output / token_usage)"]
  M["Manager agent (hierarchical only)"] -.->|"plans, delegates, validates"| T1

Agent. role, goal and backstory are required and make up the persona prompt. Other options include llm, tools, max_iter (default 20), max_rpm, max_execution_time, allow_delegation (default False), reasoning (plan before executing), respect_context_window (default True, which summarises history to fit) and function_calling_llm. The built-in code execution flags are deprecated in favour of external sandboxes such as E2B or Modal. Agent.kickoff() runs an agent on its own, with optional Pydantic response_format (agents).

Task. description and expected_output are required. A task can set an agent, context (which upstream task outputs to include), async_execution, output_pydantic/output_json (structured outputs), output_file, human_input, and guardrails. A guardrail is either a function returning (ok, value_or_error) or a natural-language criterion checked by the agent’s LLM. A failure goes back to the agent for up to guardrail_max_retries attempts (default 3), and a list of guardrails runs in order (tasks).

Process. Only two are implemented (processes):

ProcessAssignmentData flowCost/predictability
sequential (default)Fixed: each task names its agentEach output is context for the next; context= for explicit wiringCheapest, deterministic order
hierarchicalA manager (manager_llm or a custom manager_agent) allocates tasks by capability and validates resultsMediated by the managerExtra LLM calls; the manager can mis-delegate

Crew-level knobs (crews): memory, cache (tool results, default on), max_rpm, planning (a planner rewrites task descriptions with a plan before each iteration), step_callback/task_callback, and stream. Execution methods are kickoff, kickoff_for_each, native-async akickoff (recommended for concurrency), and thread-based kickoff_async. crewai replay -t <task_id> re-runs from a given task with earlier context kept.

Flows: the deterministic layer

A Flow is a class whose methods are wired by decorators (flows):

  • @start() marks entry points. Several can run, often in parallel.
  • @listen(x) runs when x finishes and receives its output. or_() fires on any upstream method, and and_() waits for all of them.
  • @router(x) returns a label, and downstream @listen("label") methods form the branches. Declare the labels (via a Literal return type or emit=) so plot() can draw them.
  • State is an unstructured dict or a Pydantic model (Flow[MyState]), and every state has an auto-generated id UUID.
  • @persist snapshots state (SQLite by default). kickoff(inputs={"id": ...}) resumes a run, and restore_from_state_id forks one.
  • @human_feedback (CrewAI 1.8.0+) pauses for human input, and it can use an LLM to map free text to routed outcomes.
  • flow.usage_metrics aggregates tokens across every crew, agent and LLM call in the run.

Synthesis: Flows are CrewAI’s answer to graph runtimes like LangGraph. The control flow is plain Python decorated into an event graph, with crews as coarse-grained “autonomous” nodes.

Memory

A unified Memory class replaces the older short-term, long-term, entity and external memory types. Memories go in LanceDB (by default ./.crewai/memory) as a path-like scope tree. On save, an LLM infers scope and importance. Recall is either shallow (pure vector search) or deep (the default: an LLM-driven multi-step flow, skipped for queries under 200 characters). Ranking blends semantic similarity, recency (30-day half-life) and importance, weighted 0.5/0.3/0.2. The default embedder is OpenAI text-embedding-3-large (memory). See agent memory, embeddings and vector databases.

Comparison

DimensionCrewAIAutoGen (AgentChat)Google ADKOpenAI Agents SDK
Mental modelTeam with roles and tasksAgents in a conversationAgents + workflow graphAgents + handoffs
Unit of workTask with expected_outputMessage/turnNode / agent invocationRun turn
Deterministic layerFlowsGraphFlow (now Agent Framework workflows)Workflow agents / 2.0 graphsNone built in
Signature featureRole/task scaffolding, guardrails per taskCode-executing agentsMulti-language, A2A, evalGuardrails, tracing

Row sources: Notebook for CrewAI vs AutoGen; ADK and OpenAI columns are Synthesis from their pages.

Limitations and failure modes

  • Persona prompts aren’t control. Role and backstory steer style. They don’t guarantee behaviour, so put correctness in expected_output, structured outputs and guardrails. (Synthesis.)
  • Hierarchical overhead. The manager adds LLM calls and can mis-delegate. Its validation criteria aren’t documented beyond “the manager reviews outputs” (processes).
  • Silent failures. Background memory saves emit events instead of raising errors. An unknown Flow state ID silently starts fresh instead of erroring (memory, flows).
  • Memory privacy and lock-in. Saves and deep recall send content to the configured LLM, and changing the embedding model can break existing stores (memory).
  • OpenAI-flavoured defaults. The default LLM is OPENAI_MODEL_NAME or gpt-6-luna (as of 2026-11), and the default embedder is OpenAI. Override both explicitly in regulated or non-OpenAI deployments (agents, memory).
  • General multi-agent cost. Multiple agents add latency, tokens and loops that may never terminate. A single agent or a plain workflow is often better (Notebook).

When to use it, and when not

Use it when the work naturally decomposes into named roles and ordered steps with checkable outputs: content pipelines, research-then-write, business back-office automation. It is also good when you want a readable prototype fast and a path to deterministic control via Flows (Notebook).

Avoid it when you need fine-grained control of every model call and state transition (LangGraph), when the path is open-ended and conversational or code-execution-centric (AutoGen / Agent Framework), or when one agent with good tools would do.

Sources

Suggest changes →