How to Build an AI Agent with CrewAI: A Beginner’s Step-by-Step Guide
If you want to learn how to build an AI agent with CrewAI as a beginner, the good news is that the framework hides most of the hard parts. You describe who your agents are and what work they should do, and CrewAI handles the coordination. You still need to understand a few core ideas, set up Python correctly, and avoid some predictable mistakes.
This guide walks through the whole process: what CrewAI is, how its pieces fit together, how to install it, how to build a small two-agent research-and-writing crew, and how to fix the errors beginners hit most often. Version details change quickly in this space, so the article points out where to check the official documentation.
Answer
To build an AI agent with CrewAI, install Python 3.10 to 3.13, install the CrewAI command-line tool, generate a project with crewai create crew, define agents and tasks in configuration files, add your LLM API key to a .env file, then run crewai install and crewai run.
What CrewAI Is (and What It Isn’t)
CrewAI is an open-source Python framework for building systems where several AI agents, each with a defined role, work together on a job. Instead of sending one giant prompt to a language model and hoping for the best, you split the job into roles. One agent might research a topic, a second might write a summary, and a third might check the result.
The framework does not contain a language model itself. It sits on top of models from providers such as OpenAI, Anthropic, or Google, or on local models you run yourself. CrewAI’s job is orchestration: giving each agent its instructions, passing outputs between steps, and letting agents use tools such as web search.
It is also not magic. An agent is only as good as the model behind it, the clarity of its instructions, and the tools it can access. Beginners often expect autonomous behavior that “just works.” In practice, results depend heavily on how carefully you write roles, goals and task descriptions.
The Four Concepts You Need First
Almost everything in CrewAI maps to four ideas. Learn these and the rest of the documentation becomes much easier to read.
| Concept | What it is | Everyday analogy |
| Agent | An AI worker with a role, goal and backstory | A team member with a job title |
| Task | A specific assignment with a description and expected output | A ticket or work order |
| Crew | A group of agents and tasks, plus the rules for running them | The team and its project plan |
| Tool | A capability an agent can use, such as search | Software the team member can open |
Agents
An agent is defined mainly by three text fields: a role (its job title), a goal (what it is trying to achieve), and a backstory (context that shapes how it behaves). You can also assign a specific model to each agent and give it tools.
These fields work as prompts. A vague role like “Helper” produces vague behavior. A role like “Senior Technology Researcher who verifies claims against multiple sources” gives the model something concrete to act on.
Tasks
A task describes what needs to be done and what a good result looks like. The most important fields are the description and the expected output. The expected output is easy to neglect, but it tells the agent when it is finished and in what format.
A task is assigned to an agent. A later task can use the result of an earlier one, which is how you build a pipeline.
Crews and processes
A crew combines agents and tasks and decides how they run. The simplest option is a sequential process, where tasks run one after another in order. CrewAI also supports a hierarchical process, where a manager agent or model delegates work. For a first project, sequential is the right choice because you can follow exactly what happens at each step.
Tools
Tools let agents do things a language model cannot do alone, such as searching the web or reading files. CrewAI ships with a library of tools, and you can write your own. A web-search tool such as the Serper-based one requires its own API key and account, so check that service’s pricing before you rely on it.
What You Need Before You Start
A supported Python version
CrewAI’s documentation states that it requires Python 3.10 or newer and older than 3.14. Check yours with python3 –version. If you have Python 3.14 installed as your default, installation may fail or behave unexpectedly, so install a supported version alongside it.
The uv package manager
CrewAI uses uv for dependency management and package handling. uv is a fast Python package tool. If you do not have it, follow the install instructions on the uv website.
An LLM provider and API key
Your agents need a language model. CrewAI works with several providers, including OpenAI, Anthropic and Google Gemini, and with local models through tools like Ollama. For a hosted model you create an account, generate an API key, and keep it private. Hosted models charge by usage, so set a spending limit in your provider dashboard before you experiment.
If you want to avoid API costs entirely, a local model is possible, but smaller local models are usually weaker at following multi-step instructions. Expect to experiment.
Basic comfort with the command line
You will type a handful of commands and edit text files. You do not need advanced Python to follow this tutorial, but you should be able to read a short script and spot where a variable is defined.
Step-by-Step: Build Your First CrewAI Agent
We will build a small “research and write” crew with two agents. A researcher gathers key points on a topic, and a writer turns them into a short briefing. This is a standard beginner pattern because it shows delegation clearly without needing external tools.
Step 1: Install the CrewAI CLI
Run this command:
uv tool install crewai
Installing through uv puts the crewai command on your machine. To update later, add the upgrade flag to the same command. Note that this upgrades the global tool only; upgrading CrewAI inside a project’s own virtual environment is a separate step covered in the documentation.
Verify the install:
crewai version
Step 2: Create a project
crewai create crew research_crew
The command may ask you to choose an LLM provider and model, and then to paste your API key.
Which scaffold will you get? This is where documentation versions diverge. Newer documentation says this command now creates a JSON-first project, with agents in separate agent files and tasks and crew settings in a crew.jsonc file. If you want the older Python and YAML layout, you add the classic flag. To follow this tutorial exactly, use:
crewai create crew research_crew –classic
If you prefer the newer layout, the concepts are identical. Only the file format changes. Run crewai create –help to see which options your installed version offers.
The classic project looks roughly like this:
research_crew/
├── .env
├── pyproject.toml
└── src/research_crew/
├── config/
│ ├── agents.yaml
│ └── tasks.yaml
├── crew.py
└── main.py
Each part has a clear job. The YAML files hold agent definitions (role, goal, backstory, tools and models) and task definitions (description and expected output). Python code in crew.py wires them together.
Step 3: Add your API key
Open the .env file and add your key. For OpenAI it looks like this:
MODEL=openai/gpt-4o-mini
OPENAI_API_KEY=your-key-here
Model names change often, so treat gpt-4o-mini as an example and check your provider’s current model list. Never commit the .env file to a public repository. Add it to .gitignore if the template has not already.
Step 4: Define your agents
Edit config/agents.yaml:
researcher:
role: >
{topic} Researcher
goal: >
Collect accurate, relevant key points about {topic}
and flag anything that is uncertain.
backstory: >
You are a careful researcher who separates well-supported
facts from speculation and states clearly when you are unsure.
writer:
role: >
Technical Briefing Writer
goal: >
Turn research notes about {topic} into a clear,
beginner-friendly briefing.
backstory: >
You explain complex topics in plain language and never
add facts that are not in the research notes.
The {topic} placeholder is filled in when you run the crew. Passing inputs at kickoff makes CrewAI substitute the placeholder in all agent and task text.
Two beginner lessons are hiding here. First, the writer’s backstory tells it not to invent facts, which reduces the chance of fabricated details. Second, each agent has one clear job. Agents with overlapping or fuzzy responsibilities tend to produce muddled output.
Step 5: Define your tasks
Edit config/tasks.yaml:
research_task:
description: >
Research {topic}. Identify the five most important points
a beginner should know, and note any limitations or
disagreements.
expected_output: >
A bulleted list of five key points, each with one or two
sentences of explanation.
agent: researcher
writing_task:
description: >
Using the research notes, write a briefing on {topic}
for a beginner audience.
expected_output: >
A briefing of about 300 words with a short introduction,
three to five clear paragraphs, and a one-sentence takeaway.
agent: writer
output_file: output/briefing.md
The expected_output field matters. Compare “write something about {topic}” with the version above. The detailed version gives the model a measurable target, which usually produces more consistent results.
Step 6: Connect everything in crew.py
The generated crew.py file contains a class that loads your YAML. The structure typically resembles this:
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
@CrewBase
class ResearchCrew:
“””Research and writing crew”””
@agent
def researcher(self) -> Agent:
return Agent(config=self.agents_config[“researcher”], verbose=True)
@agent
def writer(self) -> Agent:
return Agent(config=self.agents_config[“writer”], verbose=True)
@task
def research_task(self) -> Task:
return Task(config=self.tasks_config[“research_task”])
@task
def writing_task(self) -> Task:
return Task(config=self.tasks_config[“writing_task”])
@crew
def crew(self) -> Crew:
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
)
The template generated for your version may differ slightly, for example in type hints or imports. When it does, trust the generated file over this snippet. Treat this code as a map of the structure rather than something to paste blindly.
Setting verbose=True prints the agents’ reasoning steps to your terminal. For a beginner this is the single most useful setting, because you can watch each agent work and see where things go wrong.
Step 7: Set the input and run
In main.py, set the topic your crew should work on:
inputs = {“topic”: “how AI agents work”}
Then, from the project’s root folder, install dependencies and run:
crewai install
crewai run
The documentation says to run the install command before running your crew, and to execute the run command from the root of the project. You should see the researcher work first, then the writer, and finally a briefing saved to output/briefing.md.
The first run can take a minute or more, depending on the model. If nothing prints for a long time, check your API key and internet connection before assuming something is broken.
Understanding What Just Happened
When you ran the crew, CrewAI did the following in order:
- It loaded both agents and both tasks from your YAML files.
- It replaced {topic} with your input.
- It ran the research task using the researcher agent and your chosen model.
- It passed that output to the writing task as context.
- It wrote the final result to your output file.
Because the process is sequential, the writer only sees what the researcher produced. This is both a strength and a weakness. It keeps the pipeline predictable, but a weak research step guarantees a weak briefing. If the final result disappoints you, check the research output first.
Adding Tools to Your Agent
An agent without tools can only draw on what the language model already knows. That knowledge has a cutoff date, so for anything recent the agent may be out of date or may guess.
To give your researcher live information, you can attach a search tool. The usual pattern is to install the extra tools package, get an API key for the search service, add that key to .env, and pass the tool to the agent in crew.py. A few cautions apply:
- Search tools usually have their own pricing and rate limits. Check the provider’s current terms.
- Each tool call adds time and token cost.
- Give an agent only the tools it needs. More tools give the model more chances to choose the wrong one.
- Tell the agent in its backstory or task when to use a tool and what to do if results are poor.
Because the exact tool names and install commands change between releases, follow the current CrewAI tools documentation rather than copying commands from older tutorials.
Sequential vs. Hierarchical Processes
| Feature | Sequential | Hierarchical |
| How it works | Tasks run in a fixed order | A manager agent or model assigns and reviews work |
| Predictability | High | Lower |
| Cost | Usually lower | Usually higher, because of manager calls |
| Best for | Pipelines with clear steps | Complex jobs where the plan is not fixed |
| Beginner-friendly | Yes | Not as a first project |
Community templates describe both approaches: sequential pipelines, or hierarchical orchestration with a manager persona or model. Start sequential. Move to hierarchical only when you have a real reason, such as a job whose steps genuinely cannot be known in advance.
Choosing and Controlling Your Model
You can assign the same model to every agent or different models to different agents. A common cost-saving idea is to use a stronger model for reasoning-heavy work and a cheaper one for simple formatting. One deployment guide notes that you can assign different models to different agents through the llm setting. The tutorial in this article uses one model for simplicity.
When you compare models, test them on your own task with the same inputs. Public benchmarks do not always predict how a model handles your specific instructions.
Cost, Privacy and Safety Considerations
Cost. Multi-agent systems use more tokens than single prompts because every agent reads instructions and previous outputs. Costs grow with the number of agents, task length, tools, and retries. Set provider-side spending limits, start with short inputs, and check usage after each experiment.
Privacy. Anything you send to a hosted model leaves your machine. Do not put passwords, personal data, confidential business documents, or customer information into prompts unless you have reviewed your provider’s data policies and your organization allows it. Local models keep data on your hardware, which may suit sensitive work.
Accuracy. Agents can state wrong things confidently. Treat outputs as drafts. Verify facts, figures, quotes and links before publishing or acting on them.
Secrets. Keep API keys in .env files or a secrets manager. Never paste them into code you share.
Enterprise options. CrewAI also offers a hosted option, called AMP, that requires no installation, and a self-hosted option for organizations. Pricing and features for these change, so review the official pages directly if you need them. This tutorial covers only the open-source framework.
Common Beginner Mistakes and How to Fix Them
Installation fails or the CLI is not found
Check your Python version first, since a version outside the supported range is a common cause. Confirm uv is installed and that its tool directory is on your PATH. Close and reopen the terminal after installing.
AuthenticationError or “incorrect API key”
Check that the key is in the .env file inside the project, that the variable name matches your provider, and that there are no extra spaces or quotation marks. One tutorial points out that echoing the environment variable is a quick way to confirm that it is set. Also confirm the key belongs to an account with billing enabled if your provider requires it.
The model name is not recognized
Model identifiers change. Copy the exact name from your provider’s current documentation, including any provider prefix that your CrewAI version expects.
The output is generic or off-topic
This is almost always an instruction problem. Make the role specific, state the audience in the task, and write a more precise expected output. Add constraints, such as word count, format, and what to exclude.
The agents loop or take too long
Narrow each task. Remove unneeded tools. Check the verbose output to see whether an agent is repeatedly retrying a failed tool call. Simplify before adding complexity.
The result contains invented facts
Add an instruction to separate sourced facts from assumptions, give the agent a search tool, and add a review task or review it yourself. No prompt eliminates fabrication entirely.
YAML errors
YAML is sensitive to indentation. Use spaces, not tabs, keep keys aligned, and make sure agent and task names in the YAML match the names used in crew.py. A name mismatch is a classic cause of KeyError messages.
Following an outdated tutorial
CrewAI changes quickly. If a command, import or file layout in a tutorial does not match what your installation generated, trust the official docs and your generated project over the tutorial.
Practical Ways to Improve Your First Crew
Once the basic version works, change one thing at a time so you can see what each change does.
- Add a reviewer agent that checks the writer’s output against the research notes and flags unsupported claims.
- Add a search tool to the researcher so it can use current information.
- Tighten the expected output by specifying a template, such as headings and word counts.
- Test different models on identical inputs and compare quality, speed and cost.
- Change inputs to confirm the crew handles several topics, not just your first test.
Keep a simple log of each change and what happened. That habit is more valuable than any single tip, because it teaches you how your chosen model responds to your instructions.
When CrewAI May Not Be the Right Choice
CrewAI suits workflows where role-based collaboration is natural, such as research, content pipelines and analysis. It may be more than you need for a task a single well-written prompt can handle. A single call is cheaper, faster and easier to debug.
Other frameworks take different approaches, such as graph-based control over exact steps. If you need very precise, deterministic control over the flow of work, compare alternatives before committing. A fair comparison requires testing each framework on your own task, which this article has not done, so evaluate current documentation for the tools you are considering.
Conclusion
Building your first CrewAI agent comes down to a short sequence: check your Python version, install the CLI with uv, scaffold a project, add your API key, describe your agents and tasks clearly, and run the crew. The framework does the coordination, but the quality of your result depends on the clarity of your instructions and on how well you check the output.
Your next step is to run the two-agent example above, read the verbose output line by line, and then change one variable at a time. Once that feels comfortable, add a tool or a reviewer agent, and consult the official CrewAI documentation for current commands and options.
Frequently Asked Questions
Is CrewAI free to use?
The open-source framework is free to install. You still pay for the services your agents use, such as language model API calls and any paid tools. CrewAI’s hosted AMP option is a separate product with its own signup. Check current pricing on the official site.
Which Python version does CrewAI need?
The documentation states that CrewAI needs Python 3.10 or newer and older than 3.14. Check your version with python3 –version before installing.
Do I need to know advanced Python to use CrewAI?
No. Beginners can build a working crew by editing configuration files and running commands. Basic Python helps when you customize crew.py, add tools, or debug errors.
Can I use CrewAI without paying for an API?
Possibly. Tutorials list Ollama as a way to run models locally for free. You will need suitable hardware, and smaller local models may follow complex instructions less reliably than hosted ones.
What is the difference between an agent and a crew?
An agent is a single AI worker with a role and goal. A crew is a team of agents plus the tasks they perform and the process that organizes them.