How to run a first CrewAI crew

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:

crewai create crew research_crew
cd research_crew

The CLI creates this JSON-first project:

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:

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:

{
  "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:

{
  "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:

{
  "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:

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:

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
• Quickstart