# CrewAI Tutorial: From Install to Your First Running Crew

> Install CrewAI with uv on Python 3.10 to 3.13, scaffold a JSON-first crew, add your LLM and Serper keys, run it, build a first flow and deploy it to AMP.

_Source: https://professionalstoolkit.com/articles/crewai-tutorial — The Professional's Toolkit · updated November 2026_

---

Four commands and two API keys get a first CrewAI crew running. You need Python 3.10 or newer and below 3.14. Install the CLI with `uv tool install crewai`, scaffold a project with `crewai create crew`, then run `crewai install` and `crewai run` from the project folder [1]. New projects are JSON-first, with agents in `agents/*.jsonc` and the crew in `crew.jsonc`; the old YAML layout now needs `--classic`. The framework is free under the MIT license. **Your model provider and your search API bill you directly.** That is the whole path.


**4 commands** — uv tool install crewai, crewai create crew, crewai install, crewai run.



- **3.10 to <3.14** — Supported Python range
- **2 keys** — LLM provider plus Serper.dev for the official tutorials
- **50 a month** — Workflow executions on the free AMP Basic plan


## What to have ready before the first command

CrewAI manages dependencies with uv, and the official install path is `uv tool install crewai`. The CLI page also documents `pip install crewai`, and since May 2026 the CLI ships as its own `crewai-cli` package. Check your interpreter first. The supported range is **Python 3.10 or newer and below 3.14**, so tutorials from 2024 and 2025 that mention 3.7, or a ceiling below 3.13, are out of date. On Windows, a chroma-hnswlib build error can stop the install; the fix the docs give is Visual Studio Build Tools with the Desktop development with C++ workload.

One install detail surprises people. CrewAI's internal packages skip dependencies released in the last 3 days, a supply-chain precaution, so a brand-new transitive release will not resolve right away. Then gather keys. The official crew and flow tutorials need a key for your LLM provider plus a Serper.dev key, stored as `SERPER_API_KEY`, for web search. CrewAI's SerperDevTool page notes that Serper offers a free tier. The default model is an OpenAI one, named `gpt-6-luna` since the November 2026 release and set through `OPENAI_MODEL_NAME`, so the default path assumes an OpenAI key. Every call is billed by that provider, not by CrewAI.


> 💡 **Put both keys in .env first:** The tutorials need your LLM key and SERPER_API_KEY. crewai run asks for a missing model key, but setting both up front avoids a stalled first run.


## Scaffolding a crew: JSON by default, YAML on request

Run `crewai create crew` followed by a project name. The command asks for a provider, a model and an API key, and writes them to the project's `.env` file. The CLI suggests OpenAI, Groq, Anthropic, Google Gemini and SambaNova, with any LiteLLM-supported provider behind an other option; unless you pass `--provider`, the default JSON crew uses `openai/gpt-6-luna` [2]. Model strings carry that provider prefix. The same `crewai create` command also scaffolds a `flow`, a `tool`, a `skill`, a `template` or an experimental standalone `agent`.

What lands on disk changed in June 2026. **Each agent gets its own file in `agents/*.jsonc`**, while tasks and crew settings live in `crew.jsonc`, and `crewai run` loads that JSON directly. Each agent needs a role, a goal and a backstory, plus optional tools and a model. Each task needs a description and an expected output, and it can list earlier tasks as context. Prefer Python? Add `--classic` for the older layout with `crew.py`, `config/agents.yaml`, `config/tasks.yaml` and the `@CrewBase` decorator, which remains supported. One caution applies to shared code: a JSON crew project executes local Python when its custom tools load, so open only projects you trust.

## Running the first crew and reading what it wrote

| Command | When to run it | What it does |
|---|---|---|
| `crewai install` | Once per project, before any run | Installs and locks dependencies with uv |
| `crewai run` | From the project root | Starts the crew or flow; asks for missing inputs and keys |
| `uv add` | When you want a newer version | Upgrades the package inside the project |
| `crewai flow plot` | Flow projects only | Draws the flow as an HTML page |

`crewai install` must come before `crewai run`. When the run starts, any `{placeholder}` input the tasks expect and you did not supply is asked for at the prompt. Since November 2026 `crewai run` also checks that every model's API key is set, asks for the missing ones in the terminal and saves them to `.env`. The first-crew guide builds a researcher agent with SerperDevTool. Its findings pass through task context to a later task, which writes the result to `output/report.md`. Open that file. If it holds a report, your setup works.

Keep the project current. Users who sign in with Google, or who created an account after July 2025, cannot log in from crewai versions older than 0.140.0, and the latest release is v1.15.41 from November 2026. Leave the process setting alone at first. Agents run sequentially by default, each task's output feeding the next, and the docs advise starting there before trying a hierarchical crew with a manager.


> ⚠ **crewai install does not upgrade:** It only syncs the lock file. The global CLI and the project environment upgrade separately, so use uv add to move the project to a newer CrewAI.


## Your first flow, with a crew inside one step

CrewAI's docs call Flows the recommended structure for production apps, with agents doing the work inside a crew step. Run `crewai create flow` and you get a project marked `type = flow` in `pyproject.toml`, the flow logic in `src/<project>/main.py`, a `crews` folder and a working example crew called `poem_crew`. The quickstart goes one step further [3]. Its flow keeps the topic and the report in state, then hands the topic to a one-agent crew that searches the web and writes a markdown report to disk.

The first-flow guide is the fuller exercise and **assumes basic Python**. It chains user input, a direct LLM call that returns a Pydantic structured response, and a crew of a writer and a reviewer running in sequence, all connected by `@start` and `@listen` over typed state. Note the key trap. The outline call uses `openai/gpt-4o-mini`, so `OPENAI_API_KEY` must sit in `.env` even if your agents use Gemini or Anthropic models [4]. The guide also makes a design point worth keeping: one direct LLM call is more efficient than a crew when you need a single structured output. `crewai run` detects a flow on its own and takes inputs as JSON through `--inputs`. Routers, persistence and human feedback are covered in our [guide to CrewAI Flows](/articles/crewai-flows).


> 💡 **Plot the flow before running it:** crewai flow plot draws your flow as an HTML page, a quick way to check that every @listen step is wired to the step you meant.


## What the package sends home, and how to switch it off

The open-source package sends **anonymous usage telemetry by default**. It covers versions, crew and agent metadata, tool usage counts, LLM attributes, task lifecycle and CLI create, run and deploy attempts. It records exception class names but never error messages. Because tool names and agent roles are collected, keep personal information out of both. Set `CREWAI_DISABLE_TELEMETRY`, `OTEL_SDK_DISABLED` or `CREWAI_DISABLE_TRACKING` to true, 1, yes or on to stop it; any other value leaves telemetry running. Never flip `share_crew` casually. That opt-in sends goals, backstories, task descriptions and outputs, which may hold personal data, to CrewAI to improve the library and train models.

Tracing is a separate system. It needs a free CrewAI AMP account and `crewai login`, and you switch it with `tracing=True`, the `CREWAI_TRACING_ENABLED` variable or `crewai traces enable`. On the first run a prompt asks whether to share the trace. Declining, timing out or running without a prompt discards the local buffer, and nothing is uploaded. Traces can contain prompts, inputs and outputs. The two switches do not overlap: turning tracing off leaves telemetry on, and `OTEL_SDK_DISABLED` does not stop tracing.

## Moving the crew from your laptop to CrewAI AMP

Local runs never need an account. Deployment goes to CrewAI AMP (Agent Management Platform), the paid platform built around the framework. Its Basic plan is free, with 2 automations and 50 workflow executions a month on CrewAI cloud. Fifty is also the maximum, and additional executions are not included on Basic. By our arithmetic that is about 1.7 a day across a 30-day month, enough to try a deployment but not to schedule a busy crew. The Enterprise plan is priced on request, through a Request trial button.

The CLI path is short. Run `crewai login`, then `crewai deploy create` from a project with a git origin, or add `--zip` to upload without git. After that, `status`, `logs`, `push`, `list` and `remove` manage the deployment, and the first deploy takes about a minute. Commit `uv.lock` before you start. Every AMP deployment requires it, and a missing lock file makes the build fail during dependency resolution. The `pyproject.toml` must also declare the project type, crew or flow, matching its structure.


## FAQ

**Can I follow the tutorial with a local model instead of OpenAI?**

Yes. Ollama works through the optional crewai[litellm] extra, or as an OpenAI-compatible endpoint with custom_openai and a base_url. Default memory and knowledge embeddings still call OpenAI unless you set another embedder, such as Ollama.

**Can a coding assistant scaffold a CrewAI project for me?**

The CLI writes an AGENTS.md file plus CLAUDE.md and GEMINI.md files that import it. CrewAI also publishes a skills pack that teaches Claude Code, Cursor, Codex and Gemini CLI to scaffold crews and flows.

**Do I need a crew to run a single agent?**

No. An agent can run on its own through kickoff(), and crewai create agent scaffolds a standalone agent project, a feature CrewAI labels experimental.

**Which providers connect without LiteLLM?**

OpenAI, Anthropic, Google Gemini, Azure, AWS Bedrock and Snowflake Cortex have native integrations installed as extras such as crewai[openai]. Most other providers go through the optional LiteLLM extra, and OpenAI-compatible endpoints such as Ollama or vLLM can also connect without it through custom_openai and a base_url.


## Where the researcher crew can go next

Once `output/report.md` fills reliably, extend the same project instead of starting a new one. Swap SerperDevTool for other tools from the catalog of 75+ that installs with `crewai[tools]`, and check which of them need a paid key; our [CrewAI tools guide](/articles/crewai-tools) sorts them. If you want agents to run code, use the E2B or Daytona sandbox tools, because the old code interpreter was removed in April 2026 and tutorials that still show it will fail. For shapes beyond a single researcher, the [CrewAI examples roundup](/articles/crewai-examples) maps the official crews, flows and cookbooks to the jobs they solve.



## Sources

[1] CrewAI documentation: Installation — https://docs.crewai.com/en/installation (2026-11)
[2] CrewAI documentation: CLI — https://docs.crewai.com/en/concepts/cli (2026-11)
[3] CrewAI documentation: Quickstart — https://docs.crewai.com/en/quickstart (2026-11)
[4] CrewAI documentation: Build Your First Flow — https://docs.crewai.com/en/guides/flows/first-flow (2026-11)
[5] CrewAI pricing — https://crewai.com/pricing
[6] CrewAI Terms of Use — https://crewai.com/terms-of-use
[7] AWS Marketplace: CrewAI Enterprise Platform reviews (from G2) — https://aws.amazon.com/marketplace/reviews/reviews-list/prodview-2lisdk6meykru