How to Use CrewAI: The Beginner's Guide (First Install, First Agent, the Tools Lesson, and the Flows Lane)

CodexFuse Team · 2026-11-01T10:55:06.220Z · 11 min read

What is CrewAI, exactly?

CrewAI is the open-source Python framework for building teams of AI agents — called crews — that split a job into roles and collaborate to finish it. If you want to learn how to use CrewAI, the whole idea fits in one sentence: you define agents with roles, hand them tasks, assemble them into a crew, and call kickoff. One truth to lock in before anything else: every agent is the same underlying language model wearing a different system prompt — role, goal, and backstory are prompt engineering, not separate brains.

The project lives at github.com/crewAIInc/crewAI under the MIT license, and it has been fully standalone since version 1.0 — the old LangChain dependency was removed in 2025. By September 2026 the repository had passed 59,000 stars on GitHub, making it one of the most-starred agent frameworks in the world. There is no rival-product confusion to worry about: page-one results for the framework are README mirrors and an Akamai one-click deploy app for the same framework — no unrelated product competes for the name.

If your goal is running an autonomous agent product rather than coding a crew yourself, start with the OpenClaw beginner guide — OpenClaw is the agent product you operate, while CrewAI is the framework you build crews in. And if all you need is a single block of generated text rather than a whole team of agents, a text generator gets you there in one step; CrewAI earns its keep on jobs that genuinely need multiple roles working together.

How do you use CrewAI? The 10-step arc

Every CrewAI tutorial reduces to one arc you repeat forever: install, key, agent, task, crew, kickoff, tools, scaffold, Flows. Here is the short version of that arc; the rest of this guide walks each step slowly with working code.

1. Install the framework: pip install crewai — or uv tool install crewai for the standalone CLI.
2. Put your LLM API key in a .env file — OpenAI is the default provider, and MODEL= switches to others.
3. Write your first agent: Agent(role=..., goal=..., backstory=...).
4. Write your first task: Task(description=..., expected_output=..., agent=...).
5. Assemble the crew: Crew(agents=[...], tasks=[...], process=Process.sequential).
6. Run it: crew.kickoff(inputs={'topic': '...'}) — inputs fill the placeholders in your task descriptions.
7. Read the output — point output_file='report.md' at a file so results land somewhere permanent.
8. Give an agent a tool (web search, for example) so it can act, not just talk.
9. Try the scaffold lane: crewai create crew generates the YAML project layout the docs prefer.
10. Graduate to Flows when the crew needs state, branching, or retries — the recommended production pattern.

How do you install CrewAI?

You install CrewAI with pip install crewai — that is the canonical package on PyPI. The official installation page (updated October 28, 2026) also documents uv tool install crewai, which installs the crewai command-line interface itself as a standalone tool on your PATH.

On the Python version: the official tutorial specifies Python 3.10 and above. That same page mentions an upper bound below 3.13, but the page is about eighteen months old, so confirm the current range on the installation page before you install rather than trusting the range here.

The official first-crew blog tutorial uses the scaffold lane end to end: uv tool install crewai, then crewai create crew latest-ai-development, which generates the agents and tasks YAML files; crewai install sets up dependencies, and crewai run executes the crew and writes report.md.

How do you build your first CrewAI agent?

Your crewai first agent is one import and one constructor: from crewai import Agent, then Agent(role="Senior Research Analyst", goal="Uncover cutting-edge developments in AI", backstory="You are a veteran analyst who never misses a detail", verbose=True).

The three knobs map directly to the system prompt: role is the job title, goal is the mission, backstory is the personality and expertise. Set verbose=True while learning — it prints the agent's thinking, which is how you see what each knob actually changes.

Keep agents small and specific. One agent with one clear role beats a "does everything" agent every time, because the model can only play one persona well per call — this is the practical consequence of the one-model-many-prompts truth from the first section.

How do tasks and crews fit together in CrewAI?

A Task is the unit of work: Task(description="Research the latest AI agent frameworks", expected_output="A 500-word report with sources", agent=researcher, output_file='report.md'). The description tells the agent what to do; expected_output is the contract that keeps results consistent — beginners who skip it get a different format on every run.

A Crew wires agents and tasks together: Crew(agents=[researcher, writer], tasks=[research_task, write_task], process=Process.sequential, verbose=True). Process.sequential runs the tasks in order, each task's output feeding the next — this is the beginner default and the right one for a first crew.

Here is the complete minimal crewai crew python program — one agent, one task, one crew, one kickoff call:

from crewai import Agent, Task, Crew, Process

researcher = Agent(
    role="Senior Research Analyst",
    goal="Uncover cutting-edge developments in {topic}",
    backstory="You are a veteran analyst who never misses a detail",
    verbose=True,
)

research_task = Task(
    description="Research the latest developments in {topic}",
    expected_output="A 500-word report with sources",
    agent=researcher,
    output_file='report.md',
)

crew = Crew(
    agents=[researcher],
    tasks=[research_task],
    process=Process.sequential,
    verbose=True,
)

crew.kickoff(inputs={'topic': 'AI LLMs'})

How do you give a CrewAI agent tools?

Agents without tools can only talk; tools let them act. The built-in route is from crewai_tools import SerperDevTool, attached as tools=[SerperDevTool()] on the agent — this gives it web search, and it needs SERPER_API_KEY in your .env file to work.

For your own capability, use the @tool decorator from crewai_tools on a plain Python function — this is the pattern the Exa integration docs demonstrate — or subclass BaseTool with a _run method for full control. Both patterns are verified on the current custom-tools documentation page.

Attach tools to the agent, not the crew. The agent decides when to call them mid-task, which is the whole point of agentic behavior — a tool list on the agent is what turns a chatbot into something that fetches fresh information.

How much does running CrewAI actually cost?

The framework itself is free — MIT license, no license fee, no seat fee, no usage meter inside the library. The money goes to your own API keys: OpenAI is the default model provider, and every agent loop burns tokens, so run a small task first and watch the verbose output before you hand a crew a big job.

MODEL=<provider>/<model> in your .env switches providers — the official tutorial shows a Gemini model string as the example — and tool APIs like Serper bill separately. If you would rather run local models with no per-token bill at all, the Ollama beginner guide shows how to point an agent framework at models on your own machine.

What are CrewAI Flows, and when should you use them?

Flows are CrewAI's event-driven orchestration layer: a Flow class holds a Pydantic state model, methods decorated with @start() run first, @listen(...) methods run when upstream steps finish, and @router() methods branch conditionally — you launch the whole thing with flow.kickoff(). The current Quickstart (updated October 24, 2026) states plainly that Flows are the recommended way to structure production apps.

The API surface moved fast in 2025 and 2026, so here is the honest map: the classic Crew API — the YAML/CLI scaffold, the @agent/@crew/@task decorators, crewai run — still works and is what the official how-to tutorial teaches. New projects, though, should learn Flows first and treat the Crew API as the simple lane.

Learn the Crew API to absorb the mental model — agents, tasks, crews — then build anything that runs more than once with Flows. Treat this section as your crewai flows tutorial: one Flow class, one state model, three decorators, one kickoff.

CrewAI vs LangGraph vs AutoGen — which should a beginner pick?

All three build multi-agent systems, but they start from different mental models. Here is the honest comparison, every row sourced from pages fetched for this guide:

CrewAI vs AutoGen

This is the comparison beginners actually search for, so here is the straight answer: AutoGen was Microsoft Research's conversation-driven multi-agent framework — agents reasoning together through structured messages rather than running tools in a fixed sequence. The AutoGen repository is now archived and unmaintained, with Microsoft directing new users to the Microsoft Agent Framework. For a new project in 2026, that settles it: learn CrewAI for the role-based lane, or LangGraph for the graph lane — do not start new work on AutoGen.

CrewAI vs LangGraph

The forkast.news comparison puts it well: LangGraph is more flexible but requires more setup; CrewAI and AutoGen are faster to start but less customizable. LangGraph models workflows as explicit graphs with a StateGraph, shared state, checkpoints, and human-in-the-loop as a first-class feature — power that costs you setup time. CrewAI's opinionated Agent/Task/Crew trio gets a beginner to a working crew in one file. Start with CrewAI to learn the concepts; reach for LangGraph when your agent needs to think, loop, and adapt across sessions.

How do you run a CrewAI crew on a server?

crewai run executes the scaffolded project, and for a machine that stays on, the standard path is a container: the Docker beginner guide covers the compose lane, and the what is VPS hosting guide covers where the instance lives — a small VPS is plenty for a crew that runs scheduled jobs. If you want zero setup, Akamai publishes a one-click deploy app for the open-source framework.

Keep secrets in .env and never in the code — crews authenticate with your real keys, and those keys end up in logs. Crews log everything when verbose=True, so in production point that output at a file instead of the console.

What are the beginner mistakes to avoid?

Sources

• Official CrewAI blog tutorial "Build your first CrewAI agents" (uv tool install crewai, crewai create crew, YAML configs, SerperDevTool, crewai install/crewai run, report.md, Python >3.10, crewai v0.119.0 example) — crewai.com/blog/build-your-first-crewai-agents
• Official installation page (updated 2026-10-28; uv CLI install, JSON-first projects: agents/*.jsonc, crew.jsonc, tools/) — docs.crewai.com
• Official Quickstart v1.15.30 (updated 2026-10-24; Flows are the recommended way to structure production apps) — docs.crewai.com
• Official custom-tools page v1.15.12 (updated 2026-08-05; @tool decorator, BaseTool subclass) — docs.crewai.com
• Exa integration docs (pip install crewai 'crewai[tools]' exa_py; custom Exa search tool pattern) — exa.ai/docs/integrations/crewai
• Friendly developer's guide to CrewAI (crawled 2026-10-31; concepts, Crews & Flows, OpenAI + SERPER keys, Docker, production tips) — cohorte.co
• Akamai quick-deploy app for CrewAI (one-click deploy of the open-source framework) — techdocs.akamai.com
• CrewAI framework guide (updated 2026-08-26; Agent/Task/Crew/Process, pip install crewai, MODEL key) — mobisoftinfotech.com
• CrewAI tutorial (CLI scaffold arc, agents/tasks files, expected_output, Ollama local lane) — enterprisedna.co
• Multi-agent AI systems guide (2026 Flows-architecture recommendation) — studynumberone.net
• CrewAI explainer (4 days old; concepts, not hands-on) — medium.com/@sudharsanak13
• crewAIInc/crewAI repository metadata (MIT license, star history via GitHub API) — github.com/crewAIInc/crewAI
• AutoGen docs (repository archived; new users directed to the Microsoft Agent Framework) — microsoft.github.io/autogen
• AutoGen explainer (maintenance history, AG2 fork, package lineage) — atlan.com
• LangGraph glossary (graph model, state, the CrewAI/AutoGen flexibility comparison) — forkast.news
• Building AI agents with LangGraph (StateGraph, persistence, human-in-the-loop) — dev.to

Frequently Asked Questions

Is CrewAI free to use?

Yes. The framework is MIT-licensed — no license fee, no seat fee, no usage meter in the library. You pay only for the model and tool APIs you plug in: OpenAI (the default), alternatives via MODEL=, and tool keys like SERPER_API_KEY.

What Python version does CrewAI need?

The official tutorial specifies Python 3.10 and above. That page also mentions an upper bound below 3.13, but it is about eighteen months old — confirm the current range on the docs installation page before you install.

Do I have to use OpenAI with CrewAI?

No. OpenAI is the default provider, but MODEL=<provider>/<model> in your .env switches to others — the official tutorial shows a Gemini string as an example — and the Ollama lane runs local models with no per-token cost at all.

CrewAI or AutoGen — which should I learn?

CrewAI. AutoGen was Microsoft Research's conversation-driven multi-agent framework, but the repository is now archived and unmaintained, and Microsoft points new users at the Microsoft Agent Framework. CrewAI is the active role-based lane; LangGraph is the active graph-based lane.

Is the Crew API deprecated in favor of Flows?

No. The classic Crew API still works and is what the official how-to tutorial teaches. But the current Quickstart (updated October 24, 2026) says Flows are the recommended way to structure production apps — learn the Crew API for the mental model, build real apps with Flows.