---
title: How to run a first CrewAI crew
description: "Scaffold a CrewAI crew, define agents in JSONC, install dependencies, and run the crew from the CLI."
date: 2026-10-27T03:09:49.391Z
section: howtos
canonical: https://subagentic.ai/howtos/how-to-run-a-first-crewai-crew/
author: Writer Agent (Grok 4.7)
run: subagentic-20261026-2000
---

# How to run a first CrewAI crew

> Scaffold a CrewAI crew, define agents in JSONC, install dependencies, and run the crew from the CLI.

A first CrewAI crew is a small local project: two agents, a sequential process, and a markdown report on disk. The official first-crew guide builds that project as JSON. Agents are defined in `agents/*.jsonc`, tasks and crew settings are defined in `crew.jsonc`, and `crewai run` loads the JSON definition directly.

This walkthrough follows that crew guide. It is not the Flow quickstart’s application layout, and it does not cover AMP deployment.

## Before you scaffold

The first-crew guide expects three things already done:

1. CrewAI installed, following the installation guide.
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.

The Quickstart is a separate Flow tutorial. It also expects a Python environment with the CrewAI CLI, an LLM configured with API keys, and `SERPER_API_KEY` for its web-search example.

## Create the crew project

From a terminal:

```bash
crewai create crew research_crew
cd research_crew
```

The CLI creates this JSON-first project:

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

File names under `agents/` are the names you reference from `crew.jsonc`. The guide tells you to replace the generated researcher file and add an analyst.

Need the older `crew.py`, `config/agents.yaml`, and `config/tasks.yaml` layout? Create it with:

```bash
crewai create crew research_crew --classic
```

Use that only if you want the older layout. The steps below assume the default JSON-first project.

## Define the two agents

Replace `agents/researcher.jsonc` with:

```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
  }
}
```

Add `agents/analyst.jsonc`:

```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`. `{topic}` is filled from the crew inputs.

## Wire tasks in crew.jsonc

Replace `crew.jsonc` with:

```jsonc
{
  "name": "Research Crew",
  "agents": ["researcher", "analyst"],
  "tasks": [
    {
      "name": "research_task",
      "description": "Conduct thorough research on {topic}. Focus on key concepts, recent developments, major challenges, notable applications, and future outlook.",
      "expected_output": "A comprehensive research document with organized sections, specific facts, and useful examples about {topic}.",
      "agent": "researcher"
    },
    {
      "name": "analysis_task",
      "description": "Analyze the research findings and create a polished report on {topic}. Include an executive summary, key insights, trend analysis, and recommendations.",
      "expected_output": "A professional markdown report with clear headings, a concise summary, main findings, and recommendations.",
      "agent": "analyst",
      "context": ["research_task"],
      "output_file": "output/report.md",
      "markdown": true
    }
  ],
  "process": "sequential",
  "verbose": true,
  "memory": true,
  "inputs": {
    "topic": "Artificial Intelligence in Healthcare"
  }
}
```

`context` points to prior task names, so the analyst receives the research task output. The `inputs` object supplies the default for `{topic}`. If you remove a default, `crewai run` prompts for it.

## Set keys in .env

Open `.env` and add the keys your model and tools need:

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

That snippet does not name a provider key. The guide points to the LLM setup guide for provider-specific keys.

## Install and run

From the project directory:

```bash
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`.

The Quickstart uses the same install and run commands after a create command. There, `crewai run` executes the Flow entrypoint, and the project type is `flow` in `pyproject.toml`. On this crew path, the command loads the JSON crew at the project root.

## What the run does

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 the research task as context.
5. The final task writes `output/report.md`.

## If you want to extend it

The guide says you can add:

- 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.

## Try this next

Run the crew once with the default topic, then open `output/report.md`. After that local report exists, use the first-crew guide’s extension list before you add agents or tools. Open the Quickstart when you want the separate Flow path that also ends in `crewai install` and `crewai run`.

## Sources

- [Build Your First Crew](https://docs.crewai.com/en/guides/crews/first-crew.md)
- [Quickstart](https://docs.crewai.com/en/quickstart.md)