Build a Research Crew

Pasting every file at once does not teach you how to build. This module walks install → create → the CLI questions for agents and tasks → folder → each file → run, in the order you should actually do it.

A two-person newsroom: one reporter gathers facts, one writer files the story. You are the editor who sets up the desk, then hits run.

Visual Workflows

Start here — scroll inside each diagram frame to explore, then use + / − to zoom up to 200% if needed.

Overview

100%

Loading diagram...

Scroll inside the frame to explore · use + / − to zoom up to 200%

100%

Loading diagram...

Scroll inside the frame to explore · use + / − to zoom up to 200%

Key Takeaways

1.This is the only CrewAI module you run on your machine — follow the steps in order. Install tools, create the project, then answer the CLI questions about agents and tasks.
2.AI Research Crew: you type a topic → Researcher investigates → Writer writes report.md. Do not skip the create-wizard questions. Those answers become the agents and tasks.
3.Work in your Mac Terminal. Install Python check, then uv (once on the machine), then the CrewAI CLI (once on the machine).
4.When you run crewai create crew, the CLI stops and asks questions: LLM provider, then how many agents, each agent's role / goal / backstory, then each task's description / expected output. Type the answers in this module — do not press Enter on empty prompts.
5.After the wizard finishes, every later command runs inside ai_research_crew/. Confirm YAML, then crew.py, then main.py.

Learn elsewhere

→What is CrewAI
→Tasks
→Tools
→Processes

Real Example

Scenario

When the app asks Enter a topic to research, type Agentic AI. Researcher fills notes, Writer writes a Markdown report, and report.md appears in the project folder.

What you would do

If it fails: check python --version is 3.10–3.13, you ran crewai install inside ai_research_crew, and .env has OPENAI_API_KEY. If report.md is missing, writing_task needs output_file: report.md.

Build it step by step

Do these in order. Each step says where to work, what to install or edit, and when.

Step 1Check Python is installed
Where · Your Mac Terminal — any folder. Do this first, before anything else.
CrewAI needs Python 3.10, 3.11, 3.12, or 3.13. Prefer 3.11 or 3.12. If this command fails or shows 3.9, install a newer Python before you continue.
Terminal
```
1python3 --version
```
Step 2Install uv (package runner)
Where · Same Terminal, still any folder. Install once on this Mac — not inside the project yet.
uv is how the official CrewAI setup installs tools. After it finishes, close the terminal tab and open a new one so crewai is on your PATH.
Terminal
```
1curl -LsSf https://astral.sh/uv/install.sh | sh
```
Step 3Confirm uv works
Where · A fresh Terminal window, any folder.
You should see a version number. If 'command not found', the new PATH did not load — open a new terminal and try again.
Terminal
```
1uv --version
```
Step 4Install the CrewAI CLI
Where · Same Terminal, any folder. Still not inside a project. This installs the crewai command for your user.
This is the CrewAI command-line tool. You install it now so the next step can scaffold the folder structure for you.
Terminal
```
1uv tool install crewai
```
Step 5Confirm CrewAI CLI works
Where · Same Terminal, any folder.
You should see a CrewAI version. If this fails, repeat the uv install and open a new terminal.
Terminal
```
1crewai version
```
Step 6Create the project folder
Where · Pick a parent folder first, for example Documents. cd there, then run create. Stop after this command — do not paste extra lines yet.
This command does not finish instantly. The CLI creates the folder, then pauses and asks questions. Stay in this terminal. Do not type cd ai_research_crew until every question is answered, or those extra lines will be used as answers.
Terminal
```
1cd ~/Documents2crewai create crew ai_research_crew
```
Step 7Answer the LLM provider questions
Where · Same Terminal, still inside the create wizard. These questions come first on most CrewAI versions.
Pick OpenAI for this project. gpt-4o-mini is enough. You can paste your API key now, or press Enter to skip and add it in .env later. If a question is not shown, skip this step.
1. When it asks
  Select a provider to set up (openai, anthropic, gemini, groq, ollama, other)
  openai
2. When it asks
  Select a model to use for openai
  gpt-4o-mini
Step 8Answer how many agents, then Agent 1
Where · Same Terminal, still in the create wizard. If it never asks about agents, skip ahead — your version scaffolds default YAML instead.
This project needs two agents. Agent 1 is the researcher. Role = who they are. Goal = what they try to achieve. Backstory = experience that shapes how they think. Include {topic} so the run prompt can fill it later. Press Enter after each answer.
1. When it asks
  How many agents do you want to create?
  2
2. When it asks
  Agent 1 — name (used in YAML / code)
  researcher
3. When it asks
  Agent 1 — role
  Senior AI Researcher
4. When it asks
  Agent 1 — goal
  Research {topic} and identify the most important, accurate, and useful information about it.
5. When it asks
  Agent 1 — backstory
  You are an experienced AI researcher who specializes in analyzing emerging technologies and extracting reliable information from multiple sources.
Step 9Answer Agent 2 — the writer
Where · Same Terminal, still in the create wizard. This is the second of the two agents.
Do not give the writer the same role as the researcher. The writer only turns research notes into a report. If it also asks for tools, LLM, or allow_delegation, leave those blank / default and press Enter.
1. When it asks
  Agent 2 — name
  writer
2. When it asks
  Agent 2 — role
  Technical Report Writer
3. When it asks
  Agent 2 — goal
  Transform the research findings about {topic} into a clear, structured and useful technical report.
4. When it asks
  Agent 2 — backstory
  You are an expert technical writer who can transform complex technical information into concise, understandable documentation.
Step 10Answer how many tasks, then Task 1
Where · Same Terminal, still in the create wizard. Tasks come after agents.
Two tasks, one per agent. Description = what to do. Expected output = what 'done' looks like. Assign Task 1 to researcher. Keep {topic} in the description.
1. When it asks
  How many tasks do you want to create?
  2
2. When it asks
  Task 1 — name
  research_task
3. When it asks
  Task 1 — description
  Research the topic: {topic}. Investigate the most important concepts, current developments, practical applications, advantages, limitations, and important considerations. Focus on useful and accurate information.
4. When it asks
  Task 1 — expected output
  A detailed research document containing: key concepts, important developments, practical applications, advantages, limitations, and important considerations.
5. When it asks
  Task 1 — which agent should do this?
  researcher
Step 11Answer Task 2 — the report
Where · Same Terminal, last questions in the create wizard. After these, the CLI finishes and the folder exists.
Assign this task to writer. If it asks for an output file, type report.md — that is how the Markdown file appears after a successful run. If it asks for process, pick sequential.
1. When it asks
  Task 2 — name
  writing_task
2. When it asks
  Task 2 — description
  Using the research produced by the researcher, create a comprehensive technical report about {topic}. Organize the report with clear headings and concise explanations.
3. When it asks
  Task 2 — expected output
  A polished Markdown report about {topic} containing: Introduction, Key concepts, Current developments, Applications, Advantages, Limitations, and Conclusion.
4. When it asks
  Task 2 — which agent should do this?
  writer
5. When it asks
  Task 2 — output file (if asked)
  report.md
6. When it asks
  Process (if asked): sequential or hierarchical?
  sequential
Step 12Enter the project folder
Where · Only after the create wizard prints that the project was created and returns you to a normal prompt.
Now it is safe to cd. If you cd'd during the questions, the extra text became an agent name or task description — delete that folder and run create again.
Terminal
```
1cd ~/Documents/ai_research_crew
```
Step 13Look at the files the CLI created
Where · Inside ai_research_crew/ (you should already have cd'd here).
You should see .env, pyproject.toml, and src/ai_research_crew/ with main.py, crew.py, config/agents.yaml, config/tasks.yaml, and tools/. Newer CLI versions may create agents/*.jsonc and crew.jsonc instead. Either way, the next steps make the files match this research crew — do not create a second project.
Terminal
```
1ls -la && ls src/ai_research_crew && ls src/ai_research_crew/config
```
Step 14Install project dependencies
Where · MUST be inside ai_research_crew/ — the folder that contains pyproject.toml. Not your home folder.
This downloads the Python packages this crew needs. If you run it in the wrong directory, imports will fail later.
Terminal
```
1crewai install
```
Step 15Add your OpenAI API key
Where · File: ai_research_crew/.env (project root, next to pyproject.toml). Never commit this file.
Open .env in Cursor. Put your real key on the right of the equals sign. No quotes. Save the file. The crew reads this when it starts — you do not paste the key into Python.
.env
```
1OPENAI_API_KEY=sk-your-real-key-here
```

Step 16Write the two agents

Where · File: src/ai_research_crew/config/agents.yaml — open it and make it match this exactly.

If you typed the wizard answers above, this file should already be close. Open it anyway. Role, goal, and backstory must match. {topic} is filled later from main.py. Researcher finds facts. Writer turns facts into a report. Do not give both agents the same role. If the file looks different, replace the whole file.

src/ai_research_crew/config/agents.yaml

1researcher:2  role: >3    Senior AI Researcher4  goal: >5    Research {topic} and identify the most important,6    accurate, and useful information about it.7  backstory: >8    You are an experienced AI researcher who specializes9    in analyzing emerging technologies and extracting10    reliable information from multiple sources.11
12writer:13  role: >14    Technical Report Writer15  goal: >16    Transform the research findings about {topic}17    into a clear, structured and useful technical report.18  backstory: >19    You are an expert technical writer who can transform20    complex technical information into concise,21    understandable documentation.

Step 17Write the two tasks

Where · File: src/ai_research_crew/config/tasks.yaml — open it and make it match this exactly.

If the create wizard asked for task description and expected output, those answers landed here. Confirm agent: researcher and agent: writer match the names in agents.yaml. output_file: report.md is why a Markdown file appears after a successful run. Sequential process will run research_task first, then writing_task. If anything is missing, replace the whole file.

src/ai_research_crew/config/tasks.yaml

1research_task:2  description: >3    Research the topic: {topic}.4
5    Investigate the most important concepts, current6    developments, practical applications, advantages,7    limitations, and important considerations.8
9    Focus on useful and accurate information.10  expected_output: >11    A detailed research document containing:12    - Key concepts13    - Important developments14    - Practical applications15    - Advantages16    - Limitations17    - Important considerations18  agent: researcher19
20writing_task:21  description: >22    Using the research produced by the researcher,23    create a comprehensive technical report about {topic}.24
25    Organize the report with clear headings and concise26    explanations.27  expected_output: >28    A polished Markdown report about {topic} containing:29    - Introduction30    - Key concepts31    - Current developments32    - Applications33    - Advantages34    - Limitations35    - Conclusion36  agent: writer37  output_file: report.md

Step 18Wire the crew in Python

Where · File: src/ai_research_crew/crew.py — replace the whole file.

Do this after YAML, not before. @CrewBase loads those YAML files. Process.sequential means Researcher finishes, then Writer starts with that research. verbose=True prints the loop so you can see it think.

src/ai_research_crew/crew.py

1from crewai import Agent, Crew, Process, Task2from crewai.project import CrewBase, agent, crew, task3
4
5@CrewBase6class AiResearchCrew:7    agents_config = "config/agents.yaml"8    tasks_config = "config/tasks.yaml"9
10    @agent11    def researcher(self) -> Agent:12        return Agent(13            config=self.agents_config["researcher"],14            verbose=True,15        )16
17    @agent18    def writer(self) -> Agent:19        return Agent(20            config=self.agents_config["writer"],21            verbose=True,22        )23
24    @task25    def research_task(self) -> Task:26        return Task(27            config=self.tasks_config["research_task"],28        )29
30    @task31    def writing_task(self) -> Task:32        return Task(33            config=self.tasks_config["writing_task"],34        )35
36    @crew37    def crew(self) -> Crew:38        return Crew(39            agents=self.agents,40            tasks=self.tasks,41            process=Process.sequential,42            verbose=True,43        )

Step 19Create the entry point

Where · File: src/ai_research_crew/main.py — replace the whole file.

This is what starts when you run the crew. It asks you for a topic, puts it in inputs['topic'] (that fills {topic} in YAML), then kickoff() runs Researcher then Writer.

src/ai_research_crew/main.py

1from ai_research_crew.crew import AiResearchCrew2
3
4def run():5    topic = input("Enter a topic to research: ")6
7    inputs = {8        "topic": topic9    }10
11    result = AiResearchCrew().crew().kickoff(inputs=inputs)12
13    print("\n\n==============================")14    print("FINAL RESULT")15    print("==============================\n")16    print(result)17
18
19if __name__ == "__main__":20    run()

Step 20Run the crew
Where · Terminal, inside ai_research_crew/ (the folder with pyproject.toml). After every file above is saved.
Use the official CLI. When it asks, type a topic such as Agentic AI and press Enter. First run can take a minute while models load. Watch Researcher, then Writer.
Terminal
```
1crewai run
```
Step 21If the CLI run fails, run main.py directly
Where · Still inside ai_research_crew/.
Same crew, different starter. You should still be prompted for a topic.
Terminal
```
1python src/ai_research_crew/main.py
```
Step 22Find the report
Where · Project root ai_research_crew/ — same folder you ran the command from.
Because writing_task has output_file: report.md, a Markdown file should appear after the writer finishes. Open it in Cursor. That is the finished sequential crew: topic in, report out.
Terminal
```
1ls -la report.md && head -20 report.md
```
Step 23Optional next — give the researcher a tool
Where · Same project, after the basic crew already runs. Do not start here.
The version you just ran is multi-agent orchestration. To make the researcher actually agentic, attach a web search tool so the loop becomes think → search_web() → observe → think again. Add that only after report.md is working.

Commands

Commands to Remember

python3 --version # do this first, anywhere
uv tool install crewai # once on this Mac
cd ~/Documents && crewai create crew ai_research_crew # then answer the wizard — do not cd yet
cd ~/Documents/ai_research_crew # only after the create questions finish
crewai install # inside the project folder only
crewai run # inside the project folder, after files are saved

Cheat Sheet

Quick recap

quick ref

•Install uv + crewai on the Mac first
•Then create the project folder
•Then answer provider + 2 agents + 2 tasks in the wizard
•Then cd into the folder
•Then crewai install inside it
•Then .env, then YAML, then crew.py, then main.py
•Then crewai run → report.md

Common Mistakes

✕Running crewai install from your home folder instead of ai_research_crew/
✕Pasting cd ai_research_crew while the create wizard is still asking questions — those lines become agent/task answers
✕Skipping the create-wizard questions for agent role, goal, backstory, and task description
✕Editing YAML before the project exists — always create crew first, answer the questions, then edit
✕Python 3.9 or 3.14+
✕Committing .env with the API key
✕Forgetting process=Process.sequential so the writer never sees the research
✕No output_file on writing_task, so report.md never appears