How to build a first CrewAI research crew

CrewAI’s current first-crew guide is JSON-first. The Build Your First Crew page, shown in the documentation at v1.15.37, creates a two-agent research crew that gathers information about a topic and writes a markdown report. Agents are defined in agents/*.jsonc. Tasks and crew settings are defined in crew.jsonc. crewai run loads that JSON definition directly.

A brand-new project will not match an older YAML walkthrough. The Python and YAML layout is still available, but only if you pass the documented classic flag. This tutorial follows the JSON-first guide only.

Prerequisites

Before the scaffold, the guide expects three things:

1. CrewAI installed, following the installation guide linked from the first-crew page.
2. An LLM API key set up, following the LLM setup guide.
3. A Serper.dev API key if you want the researcher to use web search.

Those install and provider-key steps are not repeated on the first-crew page, so finish them before you create the crew. The Serper key is only for the case where the researcher uses web search.

Create the project, then stop

Create the crew and change into it:

crewai create crew research_crew
cd research_crew

When crewai create asks Run it now?, answer n. The guide edits the crew before running it, so the first run should wait until the agent files and crew settings below are in place.

The CLI creates this JSON-first tree:

research_crew/
├── .gitignore
├── .env
├── agents/
│   └── researcher.jsonc
├── crew.jsonc
├── knowledge/
├── pyproject.toml
├── README.md
├── skills/
└── tools/

For this crew, the files you edit are the generated researcher agent file, a new analyst agent file, crew.jsonc, and the env file. The knowledge, skills, and tools directories are part of that scaffold. This first crew does not add files under them.

Need crew.py, config/agents.yaml, and config/tasks.yaml instead? Create that layout with:

crewai create crew research_crew --classic

The steps below assume you did not pass that flag.

Define the two agents

Replace the generated agents/researcher.jsonc and add agents/analyst.jsonc. The file names are the names you reference from crew.jsonc, so the researcher file is the agent named researcher and the analyst file is the agent named analyst.

agents/researcher.jsonc:

{
  "role": "Senior Research Specialist for {topic}",
  "goal": "Find comprehensive and accurate information about {topic}, with a focus on recent developments and key insights.",
  "backstory": "You are an experienced research specialist who organizes complex information into clear, useful notes.",
  // Replace with your model, for example "openai/gpt-4o".
  "llm": "provider/model-id",
  "tools": ["SerperDevTool"],
  "settings": {
    "verbose": true,
    "allow_delegation": false
  }
}

agents/analyst.jsonc:

{
  "role": "Report Analyst for {topic}",
  "goal": "Turn research findings into a clear, well-structured report.",
  "backstory": "You are a careful analyst with strong technical writing skills and a talent for extracting useful insights.",
  // Replace with your model, for example "openai/gpt-4o".
  "llm": "provider/model-id",
  "settings": {
    "verbose": true,
    "allow_delegation": false
  }
}

Replace provider/model-id with the model you use. The guide’s examples are openai/gpt-4o, anthropic/claude-sonnet-4-6, and gemini/gemini-3.7-flash. Leave the topic placeholder in the role and goal text. Crew inputs fill it at run time.

The researcher is the only agent in this sample with a tools entry, and that entry is SerperDevTool. Both agents set verbose to true and allow_delegation to false. The analyst file has no tools entry.

Define tasks and crew settings

Replace crew.jsonc with the research-crew object on the Build Your First Crew page. Use that sample as the file you save.

The object the guide shows is still specific:

• The crew name is Research Crew.
• Agents are researcher, then analyst.
• Process is sequential. Verbose is true. Memory is true.
• Inputs set the default topic to Artificial Intelligence in Healthcare. That value fills the topic placeholder. If you remove a default, crewai run prompts for it.

The tasks array has two objects, in order.

The first task is named research_task. Its description asks for thorough research on the topic, focused on key concepts, recent developments, major challenges, notable applications, and future outlook. The expected output is a comprehensive research document with organized sections, specific facts, and useful examples about the topic. The agent is researcher.

The second task is named analysis_task. Its description asks the agent to analyze the research findings and create a polished report, including an executive summary, key insights, trend analysis, and recommendations. The expected output is a professional markdown report with clear headings, a concise summary, main findings, and recommendations. The agent is analyst. Context points at the prior task name, so the analyst receives the research task output. The output file is output/report.md, and markdown is true.

Context points to prior task names. A sequential process runs tasks in array order. Change the topic string in inputs if you want a different subject, and leave the topic placeholders in the agent and task text so the input still fills them.

Copy the full crew.jsonc object from the Build Your First Crew page. Do not paste a partial fragment.

Set environment variables

Open the env file and add the keys your model and tools need. The guide shows:

SERPER_API_KEY=your_serper_api_key
# Add your model provider API key here too.

SERPER_API_KEY is the only variable name this page shows. The comment tells you to add your model provider API key as well. Provider-specific names are in the LLM setup guide, not on this page. Replace your_serper_api_key with your own key if the researcher will search the web.

Install and run

From the research_crew directory:

crewai install
crewai run

crewai run detects crew.jsonc, loads the agents from agents/, prompts for missing placeholders, and runs the crew. When the run finishes, open output/report.md.

How the handoff works

The guide’s own sequence is:

1. crew.jsonc defines the crew, task order, process, memory, and runtime inputs.
2. agents/researcher.jsonc and agents/analyst.jsonc define the agents.
3. The researcher runs first.
4. The analyst runs second with context: ["research_task"].
5. The final task writes output/report.md.

The researcher’s expected output is a research document with organized sections, specific facts, and useful examples. The analyst’s expected output is a professional markdown report with clear headings, a concise summary, main findings, and recommendations. Sequential order plus task context is what connects them. Hierarchical execution is an extension, not part of this crew. The guide says that form uses "process": "hierarchical" and a manager_llm or manager_agent.

Extend it only from a source you trust

The same page lists what you can add, without extra sample files:

• More agents, by creating new agents/<name>.jsonc files and listing them in crew.jsonc
• More tasks, by appending objects to the tasks array
• Built-in tools, by adding tool class names such as "FileReadTool" or "SerperDevTool"
• Custom tools with custom:<name>, which loads tools/<name>.py
• Hierarchical execution with "process": "hierarchical" and a manager_llm or manager_agent

Only run JSON crew projects from sources you trust. custom:<name> tools and {"python": "module.attribute"} references execute local Python code when the crew loads. A crew you wrote is a different risk from a downloaded crew.jsonc that points at local Python.

Try the report

Set the topic in inputs, replace provider/model-id on both agents, and add SERPER_API_KEY if the researcher should search. Copy the crew.jsonc sample from the Build Your First Crew page so the task names, context link, and output file match the guide, then run crewai install and crewai run. Open output/report.md and check that the analyst’s report reflects the research task. If you actually need the YAML-era project, recreate it with crewai create crew research_crew --classic instead of reshaping this JSON tree. For provider key names, use the LLM setup guide linked from the first-crew page.

Sources

• Build Your First Crew