Summary: CrewAI is an open-source framework for multi-agent teams (Crews) and stateful orchestration (Flows). This tutorial walks you from installing the CLI with uv, through a JSON-first two-agent research crew that writes a markdown report, to knowing when a Flow wrapper is worth adding. All install steps, agent files, and plan limits below are taken from CrewAI's official docs and pricing page as of 2026-11-05.
What CrewAI actually is: Crews plus Flows
CrewAI's own introduction describes the product as a framework for orchestrating autonomous AI agents and building complex workflows. The architecture has two pieces that work together rather than competing:
- Flows are the backbone: structured, event-driven workflows with state management, conditional logic, loops, and branching. Think of a Flow as the process definition that decides what runs next.
- Crews are the intelligence units: teams of role-playing agents that collaborate on a delegated task, with tools, goals, and task handoff.
In a typical production pattern, a Flow triggers, manages state, and hands a hard problem to a Crew. The Crew's agents finish the work and return a result; the Flow continues from there. You can run a Crew on its own for learning and prototypes. For anything that needs reliable sequencing, branching, or persistence, the docs recommend starting with a Flow and calling Crews from Flow steps.
A short decision frame from CrewAI's evaluating-use-cases guide: pick a Crew when you need collaborative, creative, or analytical work with some flexibility in the output shape; pick a Flow when you need precise control, structured state, conditional paths, or a mix of AI and ordinary Python. High-complexity, high-precision apps often use Flows that orchestrate multiple Crews with validation between steps. See the official screenshots at the end of this post for the Flows/Crews diagrams and the complexity-precision matrix.
Install the CrewAI CLI (uv first)
CrewAI requires Python >=3.10 and <3.14. Check with python3 --version before you install anything. The CLI is distributed through Astral's uv tool installer, not a bare pip install as the primary path in the current docs.
Step 1: Install uv
On macOS or Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
If curl is missing, the same script works with wget: wget -qO- https://astral.sh/uv/install.sh | sh.
On Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Step 2: Install the crewai CLI
uv tool install crewai
If you get a PATH warning, run uv tool update-shell and open a new terminal. On Windows, a build error around chroma-hnswlib==0.7.6 complaining that float.h cannot be opened usually means you need Visual Studio Build Tools with the "Desktop development with C++" workload.
Confirm the tool is present:
uv tool list
You should see a crewai entry. Upgrade the global CLI later with uv tool install crewai --upgrade. That upgrades the CLI tool only; upgrading the package inside a project venv is a separate step covered in CrewAI's migration guide.
Optional but useful: CrewAI 0.175.0 expects openai >= 1.13.3 if you manage the OpenAI SDK yourself. Keep API keys out of git; the scaffolded projects put them in .env.
Build your first two-agent research crew (JSON-first)
New crew projects are JSON-first. Agents live in agents/*.jsonc, tasks and crew settings live in crew.jsonc, and crewai run loads that definition directly. If you still need the older crew.py plus YAML layout, add --classic when creating the project.
Prerequisites for this walkthrough
- CrewAI CLI installed as above.
- An LLM API key configured per the LLM setup guide (for example
OPENAI_API_KEY, or whatever your chosen provider needs). - A Serper.dev API key if the researcher should search the web (
SERPER_API_KEYin.env). Without Serper, dropSerperDevToolfrom the agent tools list or the search step will fail.
Step 1: Scaffold the project
crewai create crew research_crew cd research_crew
You get a tree roughly like this: .env, agents/researcher.jsonc, crew.jsonc, knowledge/, pyproject.toml, skills/, and tools/. File names under agents/ are the names you reference from crew.jsonc.
Step 2: Define researcher and analyst agents
Replace the generated researcher file and add an analyst. The official first-crew guide uses placeholders like {topic} and a model id such as openai/gpt-4o (or Anthropic / Gemini ids). Keep the model string in provider/model-id form.
Researcher (agents/researcher.jsonc): role focused on finding recent, accurate information; goal that stresses comprehensive notes; tools including "SerperDevTool" when you have a Serper key; settings.verbose true; allow_delegation false for a predictable two-step pipeline.
Analyst (agents/analyst.jsonc): role that turns findings into a clear report; no search tool required; same LLM field pattern; verbose on, delegation off.
You do not need to invent Python classes for this starter. JSONC is enough for the first run.
Step 3: Wire tasks in crew.jsonc
The crew file lists agents by name, then a tasks array. A minimal sequential research crew looks like this in spirit (match the official guide when you paste):
research_taskassigned toresearcher, with a description and expected_output that mention{topic}.analysis_taskassigned toanalyst, with"context": ["research_task"]so the analyst receives the research output, plus"output_file": "output/report.md"and"markdown": true.- Crew-level
"process": "sequential","verbose": true, optional"memory": true, and aninputsobject with a default topic such as "Artificial Intelligence in Healthcare".
If you remove a default from inputs, crewai run prompts for the missing placeholder at runtime. That is handy when you want to reuse the same crew for different topics without editing JSON every time.
Step 4: Environment variables, install, run
Put keys in .env:
SERPER_API_KEY=your_serper_api_key # plus your model provider key, e.g. OPENAI_API_KEY=...
Then:
crewai install crewai run
crewai install syncs the project environment. Extra packages go in with uv add <package-name>. After a successful run, open output/report.md. The flow of execution is: crew.jsonc defines order → researcher runs first → analyst runs with research context → final task writes the markdown file.
How to extend without rewriting everything
Add more agents as new agents/<name>.jsonc files and list them in crew.jsonc. Append tasks to the array. Built-in tools are referenced by class name strings such as "FileReadTool" or "SerperDevTool". Custom tools use "custom:<name>", which loads tools/<name>.py. Hierarchical process mode is available with "process": "hierarchical" plus a manager LLM or manager agent. Treat untrusted JSON crew projects carefully: custom tools and Python attribute references execute local Python when the crew loads.
Optional next step: wrap the crew in a Flow
Once a standalone crew works, the quickstart shows the production-shaped pattern: scaffold with crewai create flow latest-ai-flow, keep a small research crew under the Flow's crews/ tree, load it with load_crew, and drive it from a Flow class that holds state (topic, report) with @start() and @listen steps. The Flow owns execution order; the crew does the agent work; the task's output_file still writes output/report.md.
You still run with crewai install and crewai run — the project type in pyproject.toml tells the CLI it is a Flow. Deploying to CrewAI AMP after local success uses crewai login, crewai deploy create, then status/logs/push commands documented in the quickstart. Skip the full Flow code dump here; copy the official quickstart when you are ready, and keep agent/task names consistent between crew.jsonc and the agents/ filenames.
If you are choosing architecture for a larger app, CrewAI's complexity-versus-precision matrix is worth a careful read: simple creative work can stay on a small Crew; data extraction with strict schemas often wants a Flow with structured outputs; enterprise pipelines usually combine both. Related reading on our blog: the Dify playbook for turning help docs into an AI assistant and the n8n AI agent error fixes cover neighbouring orchestration styles.
Open-source CLI vs CrewAI AMP Free vs Enterprise
The open-source path is local: you install the CLI, bring your own LLM keys, and run crews or flows on your machine. CrewAI AMP is the hosted platform (sign up at app.crewai.com). Pricing below is only what appears on the official pricing page and installation notes — no invented dollar amounts.
| Capability | Open-source CLI | CrewAI AMP Free | Enterprise (Custom) |
|---|---|---|---|
| How you get it | uv tool install crewai; Python >=3.10 and <3.14; local project with your own LLM API keys |
Sign up at app.crewai.com; no local install required for the hosted studio path | Sales / request trial; custom pricing |
| Build experience | JSON-first (or classic) projects in your editor; crewai create / crewai run |
Visual editor and AI copilot; GitHub integration | Everything in Free, plus enterprise connectors and governance features |
| Executions / scale | Limited by your machine and provider quotas | 50 workflow executions per month (Free plan also lists 50 as the maximum) | Sized to workflow; flexible overage |
| Deployment | Your laptop / your servers | CrewAI cloud | CrewAI cloud, your VPC, or your own infrastructure |
| Security & onboarding | You own keys, network, and secrets | Community support path on Free | SSO, RBAC, workload identity, PII redaction, and policies; 45-day onboarding; forward-deployed engineering and training available a la carte |
Free also lists private agent/tool repositories, templates, tracing, OpenTelemetry, guardrails, human-in-the-loop, and workflow chat in the comparison grid on the pricing page. Enterprise adds dedicated support channels, training, and on-site options that Free marks as unavailable. Treat the table as a shopping map, then confirm live limits on crewai.com/pricing before you commit a team budget.
Editor's note
Who this is for: developers who want a real multi-agent research or report pipeline on their own machine, and teams evaluating whether AMP's visual editor is enough before buying Enterprise governance. Who this is not for: people who need a no-code chatbot UI only, or who expect the framework to include free LLM calls — open-source CrewAI always brings your own provider keys.
Gotchas from the official docs:
- After
uv tool install crewai, a PATH warning means runuv tool update-shell(or fix PATH manually) beforecrewaiis found. - Windows
chroma-hnswlibbuilds that fail on missingfloat.hneed Visual Studio Build Tools with C++ desktop development. - JSON crews that use
custom:<name>tools or Python attribute references execute local Python on load — only run projects from sources you trust. - Python must be >=3.10 and <3.14; outside that range the install path will fight you.
- The first-crew and quickstart tutorials that call
SerperDevToolneedSERPER_API_KEY; missing it is a common silent failure for "web research" demos.
If your local LLM stack misbehaves while you debug CrewAI, our AnythingLLM troubleshooting guide covers a related desktop/Docker chat stack that often sits next to the same provider keys.
FAQ
Q: Is the open-source CrewAI free?
A: Yes — the open-source framework and CLI are free to install and run locally. You still pay your LLM provider (and Serper if you use web search). CrewAI AMP Free is a separate hosted tier with a visual editor, GitHub integration, and 50 workflow executions per month. Enterprise is custom-priced.
Q: Do I need a Serper API key?
A: Only if an agent lists SerperDevTool (as in the official first-crew and quickstart tutorials). Without web search you can omit that tool, or swap in other built-in tools such as file readers, and rely on the model's knowledge alone. Put SERPER_API_KEY in .env when you do use Serper.
Q: Crew vs Flow — which should I start with?
A: Start with a Crew if you want the fastest path to a collaborating multi-agent pipeline (this tutorial). Start with a Flow when you need state, branching, or production structure around that crew. CrewAI's introduction says production apps usually use both: Flow as the manager, Crew as the team that does the hard collaborative work.
Install with uv, define two JSONC agents, wire sequential tasks with context and an output file, then run — that is the shortest honest path to a working CrewAI crew. Official diagrams from the documentation are at the end of this post.
Image credit: Official diagrams from the CrewAI documentation (docs.crewai.com); CrewAI pricing page screenshot captured 2026-11-05.
Last verified: 2026-11-05
Sources: Installation, Build your first crew, Quickstart, Introduction, LLMs, Evaluating use cases, Pricing, CrewAI AMP signup.
댓글
댓글 쓰기