CrewAI: Multi-Agent Framework Guide

CrewAI is an open-source Python framework for building teams of role-based AI agents (Crews) and the event-driven workflows that direct them (Flows). It is MIT-licensed and needs Python 3.10 up to, but not including, 3.14. A commercial platform, CrewAI AMP, adds deployment and monitoring, with a free Basic plan. Checked 31 October 2026.

At a glance

What CrewAI is

The README describes it as "an open-source Python framework with high-level abstractions and low-level APIs for building production-ready multi-agent workflows." The docs' introduction calls it "the leading open-source framework for orchestrating autonomous AI agents and building complex workflows". That "leading" is the vendor's claim.

The README claims over 100,000 developers have been certified through its community courses. Again, that is the project's own number.

Where LangGraph asks you to draw a graph, CrewAI asks you to cast a team. You define agents by role, goal and tools, give them tasks, and let them work through the tasks together. The appeal is that a business person can read the setup and understand it: "a researcher, a writer and an editor."

Crews and Flows

These two terms are the whole product.

Crews

A Crew is a group of agents with specialised roles. The README lists what Crews offer: natural, autonomous decision-making between agents, dynamic task delegation, specialised roles with defined goals, and flexible problem solving. Use a Crew when the path to the answer is not known in advance and several viewpoints help.

Flows

A Flow is the application backbone. The docs say Flows define the steps, logic and data movement, manage state, respond to events, and support conditionals, loops and branching. A Flow can hand a step to a Crew and take the result back. The README lists "secure, consistent state management between tasks" and "clean integration of AI agents with production Python code".

Putting them together

The README's advice is to combine the two: Flows for the parts that must be predictable, Crews for the parts that benefit from autonomy. In plain terms, let code handle the order of operations and let agents handle the fuzzy thinking.

Install and first project

CrewAI uses uv for dependency management. From the README:

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# install the CrewAI CLI
uv tool install crewai

# verify
uv tool list

# create a crew project
crewai create crew <project_name>

# run it
crewai run

The README says crewai create crew makes a JSON-first project: agents live in agents/*.jsonc, tasks and crew-level settings live in crew.jsonc, and crewai run loads that definition directly. The folder also has knowledge/, skills/ and tools/ directories. If you prefer the older Python and YAML scaffold with crew.py, config/agents.yaml and config/tasks.yaml, add --classic.

That is a notable change from older tutorials, which show YAML and Python. If you follow a tutorial that looks different from what the CLI generates, check its date.

On Windows, the README warns of a chroma-hnswlib build error that needs Visual Studio Build Tools with the C++ workload. To upgrade the global CLI, use uv tool install crewai --upgrade; upgrading inside a project is a separate step in the docs.

Models and tools

CrewAI is not tied to one model vendor. The README has a section on connecting a crew to a model, and the framework supports hosted and local models.

Agents get tools: web search, file access, APIs, your own functions. The introduction says agents can connect to external APIs, databases and local tools. Memory and knowledge features exist (the project scaffold has a knowledge/ folder). MCP support:.

What it costs

The framework costs nothing. Your costs are model calls and, if you choose it, the CrewAI AMP platform.

From the pricing page on 31 October 2026:

The README describes the AMP Suite as adding "managed deployment, observability, governance, security, and enterprise support", with on-premise or cloud options. It says you can try the Crew Control Plane free at app.crewai.com. Seats are not mentioned on the pricing page.

A rough cost warning: multi-agent crews make many model calls. Each agent step reads context, thinks and writes. A five-agent crew on a long task can use many times the tokens of one agent doing the same work. Set a budget before you scale. Model prices are on LLM API prices.

Privacy and telemetry

CrewAI collects anonymous telemetry by default. The README lists what it takes: CrewAI and Python versions, the operating system, the number of agents and tasks, the process type, whether agents use memory or delegation, whether tasks run in parallel, the language model name, agent roles and tool names. It says no data is collected about prompts, task descriptions, backstories, goals, tool use, responses or secrets, except when you turn on share_crew. With share_crew set to True, detailed data including goals, backstories, context and task outputs is shared.

For a company with strict rules, that means two checks: whether the base telemetry is acceptable, and keeping share_crew off.

What it does well

• Easy mental model. Roles, goals and tasks map to how people already think about teams.
• Fast first demo. The CLI scaffolds a working project with one command.
• Flows for control. You can keep the process deterministic and use agents only where useful.
• MIT license. No fair-code surprises.
• Active development. A release on 29 October 2026 and a push the next day.

Limits and cautions

• Cost and latency. More agents mean more calls. Many problems do not need a team.
• Debugging. When agents delegate to one another, finding the step that went wrong takes tracing. That is what the AMP control plane sells.
• Churn. The scaffold changed from YAML to JSON-first, so old tutorials mislead. Pin versions.
• Python only. Unlike some competitors there is no TypeScript edition in the sources we read.
• Commercial pull. The README promotes AMP prominently. The framework works without it.

CrewAI compared

More are covered in AI agent frameworks and agentic AI frameworks. If you want to skip code, see AI agent platforms.

How a run unfolds

Reading the README's description of Crews and Flows, a typical run looks like this.

1. A trigger starts a Flow: a command, an API call or an event.
2. The Flow sets up its state, a shared record that later steps can read and update.
3. A step in the Flow starts a Crew and passes in what it needs, such as a topic or a ticket.
4. Inside the Crew, agents take tasks in order or delegate to one another, each using its own tools.
5. The Crew returns a result to the Flow.
6. The Flow checks the result, branches if needed (for example, retry or send to a person), and carries on.

The thing to notice is that the Flow, which is ordinary Python, decides what happens next. That is the answer to the common complaint that agent teams are unpredictable: put the unpredictable part in a box and keep the box small.

Writing good agent definitions

Role, goal and tools are the fields that matter most. A few habits help.

• Give each agent one job. "Researcher" is better than "researcher and fact checker".
• Write the goal as an outcome, such as "a list of five sources with one-line summaries", not "do research".
• Limit tools. An agent with ten tools wastes tokens deciding between them.
• Keep prompts in files. The project scaffold separates agents and tasks, so version them in git and review changes like code.

Moving to or from CrewAI

From a single-agent script, wrap your existing function as a tool and create one agent around it. From AutoGen, which Microsoft has archived, the closest concepts are agents and group chats becoming agents and Crews, but there is no migration guide for CrewAI in the sources we read, only Microsoft's own guide to its Agent Framework. Away from CrewAI, the tools and prompts are the portable parts; the crew wiring is not.

Good fits

• A content pipeline: researcher, drafter, editor, each with a defined output.
• Lead research: one agent gathers, one enriches, one summarises for a person.
• Report generation from several data sources.
• A Flow that routes incoming requests and calls a Crew only for hard ones.

Poor fits: tasks with one prompt, tasks that need strict step-by-step guarantees without a Flow, and anything where cost per run must be tiny.

Working with a coding agent

The README has a "Build with AI" section that tells you to teach your coding agent CrewAI best practices with one command, with a Claude Code route and an "other" route. That is useful, since agent code is a good fit for Claude Code or Cursor. Give the coding agent your AGENTS.md with the project conventions, and pin the CrewAI version in the prompt so it does not write against an older API. See write a good AGENTS.md.

Testing and tracing a crew

Multi-agent runs are hard to debug by reading final answers. Log each agent's task, input and output, and keep them for a few runs. Compare two runs of the same input: if the agents take different routes, tighten the task descriptions. Keep a fixed set of ten inputs with the output you expect, and re-run after changing any role, goal or tool. The AMP control plane offers tracing, and you can also write your own logging around each task.

When one agent is enough

A useful test before building a crew: write the task as one prompt with two or three tools and run it on five real inputs. If the answers are good, you have saved most of the cost. If one part keeps failing, such as fact checking, split that part into a second agent. Grow the crew only where the single agent fails.

Our take

This is an editorial reading of the repository, docs and pricing page, not a hands-on test.

CrewAI is the friendlier of the two big Python agent frameworks, and the Crews and Flows split is the right idea: use code for order, agents for judgment. The risk is overuse. It is easy to build a five-agent crew for a job that one agent with two tools would do better and cheaper.

Our advice is to start with a Flow and one agent, add a second agent only when the first one's prompt becomes a mess, and measure tokens per run from the start. If you later need durable state, human approvals and replay, LangGraph is the next stop, and your tool functions will move across.

Check telemetry settings before using it on private data. It is a small thing that is easy to miss.

Checklist

• Confirm you need multiple agents; try one agent first
• Install Python 3.10 to 3.13 and uv
• Run uv tool install crewai then crewai create crew <name>
• Keep share_crew off for private data and review telemetry
• Set a token budget and log tokens per run
• Pin the CrewAI version
• Re-check AMP pricing before buying