CrewAI Tutorial: From Install to Your First Running Crew

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.

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.

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

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.

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.

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.

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 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 maps the official crews, flows and cookbooks to the jobs they solve.