CrewAI

1.10.0 verified Mon May 11 auth: no python install: stale quickstart: stale

Python framework for orchestrating role-playing, autonomous AI agents. Agents collaborate via sequential or hierarchical processes to complete complex tasks. Built from scratch — independent of LangChain. Two core primitives: Crews (autonomous multi-agent collaboration) and Flows (event-driven, precise orchestration).

pip install crewai

Common errors

error OPENAI_API_KEY is required ↓

cause CrewAI, or its underlying dependencies like `litellm`, often defaults to requiring an OpenAI API key for validation, even when a different LLM provider or local model is intended for use.

fix

If using OpenAI, ensure your OPENAI_API_KEY is set as an environment variable or in a .env file. If using another LLM (e.g., Groq, Ollama, Google Generative AI), explicitly pass the llm parameter to your agents and crew. You might still need to set a dummy OPENAI_API_KEY="sk-dummy" in your .env file to bypass initial validation if the error persists.

error ModuleNotFoundError: No module named 'tiktoken' ↓

cause The `tiktoken` library, essential for tokenization with many LLMs and often required for embeddings, is a dependency that might not be automatically installed with the base `crewai` package or if specific 'extras' like `[embeddings]` or `[tools]` were omitted during installation.

fix

Install tiktoken explicitly. It's often beneficial to install it along with the crewai[embeddings] or crewai[tools] extras to ensure all related dependencies are met: pip install 'crewai[embeddings]' or pip install tiktoken.

error AttributeError: 'list' object has no attribute 'get' ↓

cause This error typically occurs when a list is provided in a context where a dictionary is expected, and the code attempts to call the `.get()` method (which is a dictionary method) on that list. This often happens with malformed YAML configurations for agents or tasks.

fix

Review your agent and task definitions, especially if loading from YAML files. Ensure that where dictionaries are expected (e.g., for agent configurations), you are providing a dictionary-like structure and not a list. Check for incorrect indentation or syntax in your YAML.

error ModuleNotFoundError: No module named 'crewai' ↓

cause The `crewai` library has not been installed in your current Python environment, or the environment where it was installed is not active.

fix

Install the crewai package using pip in your active Python environment: pip install crewai.

error Agent stopped due to iteration limit or time limit. ↓

cause An agent has exceeded the configured maximum number of iterations (`max_iter`) or the maximum allowed execution time (`max_execution_time`) while attempting to complete its assigned task. This can occur with complex tasks, less capable LLMs, or insufficient default limits.

fix

Increase the max_iter and/or max_execution_time parameters when initializing your agent. For example, Agent(..., max_iter=25, max_execution_time=120). If the problem persists, consider using a more powerful LLM or breaking down the task into simpler, more manageable sub-tasks.

Warnings

breaking Python <3.10 is not supported. CrewAI requires Python >=3.10 and <3.14. Installation on 3.9 will fail or produce broken behavior. ↓

fix Use Python 3.10, 3.11, or 3.12. Python 3.13 is supported but 3.14 is not yet.

breaking Task.expected_output is a required field. Omitting it raises a validation error at instantiation time. ↓

fix Always specify expected_output in every Task definition, even if just a short description string.

breaking crewai-tools is a completely separate package from crewai. Tools like SerperDevTool, FileReadTool, and WebsiteSearchTool raise ImportError if crewai-tools is not installed separately. ↓

fix pip install crewai-tools (or pip install 'crewai-tools[mcp]' for MCP support)

breaking The recommended project structure uses YAML config files (src/<project>/config/agents.yaml and tasks.yaml) with @CrewBase, @agent, @task decorators. Code-only setups from older tutorials (pre-1.0) are still valid but the YAML-first pattern is now canonical and most docs assume it. ↓

fix Use 'crewai create crew <name>' CLI command to scaffold the correct project structure with YAML configs.

breaking The crewai-tools repo (crewAIInc/crewAI-tools on GitHub) is now archived. Tool development has moved to the crewai-tools PyPI package maintained in the main crewai ecosystem. ↓

fix Install from PyPI: pip install crewai-tools. Do not use the archived GitHub repo directly.

gotcha Small open-source models (7B and below) often fail at function/tool calling within CrewAI. The framework relies heavily on the LLM's ability to generate correctly structured tool calls. ↓

fix Use models with strong tool-call support: GPT-4o, Claude 3.5+, Gemini 2.0+, or Qwen3-72B+ for reliable agentic behavior.

gotcha Windows users encounter build errors for chroma-hnswlib==0.7.6 (a memory dependency) due to missing C++ build tools. ↓

fix Install Visual Studio Build Tools with the 'Desktop development with C++' workload before pip install crewai.

gotcha crew.kickoff() is synchronous and blocking. For async contexts or FastAPI use, use crew.kickoff_async() instead. ↓

fix await crew.kickoff_async(inputs={...}) in async contexts.

gotcha Non-OpenAI LLM providers require litellm and the correct model string format: 'provider/model-name' (e.g. 'anthropic/claude-sonnet-4-5', 'ollama/gemma3'). Passing just the model name without provider prefix silently routes to OpenAI. ↓

fix Use LLM(model='anthropic/claude-sonnet-4-5', api_key=...) or set the MODEL env var to 'provider/model-name'.

Install

pip install crewai-tools

pip install 'crewai-tools[mcp]'

Install compatibility stale last tested: 2026-05-11

python os / libc variant status wheel install import disk

3.10 alpine (musl) mcp - - - -

3.10 alpine (musl) crewai - - - -

3.10 alpine (musl) crewai-tools - - - -

3.10 slim (glibc) mcp - - 6.44s 864M

3.10 slim (glibc) crewai - - 7.14s 778M

3.10 slim (glibc) crewai-tools - - 6.45s 864M

3.11 alpine (musl) mcp - - - -

3.11 alpine (musl) crewai - - - -

3.11 alpine (musl) crewai-tools - - - -

3.11 slim (glibc) mcp - - 8.36s 923M

3.11 slim (glibc) crewai - - 17.09s 762M

3.11 slim (glibc) crewai-tools - - 8.28s 923M

3.12 alpine (musl) mcp - - - -

3.12 alpine (musl) crewai - - - -

3.12 alpine (musl) crewai-tools - - - -

3.12 slim (glibc) mcp - - 9.59s 903M

3.12 slim (glibc) crewai - - 17.75s 748M

3.12 slim (glibc) crewai-tools - - 9.47s 903M

3.13 alpine (musl) mcp - - - -

3.13 alpine (musl) crewai - - - -

3.13 alpine (musl) crewai-tools - - - -

3.13 slim (glibc) mcp - - 8.95s 901M

3.13 slim (glibc) crewai - - 16.84s 747M

3.13 slim (glibc) crewai-tools - - 8.99s 901M

3.9 alpine (musl) mcp - - - -

3.9 alpine (musl) crewai - - - -

3.9 alpine (musl) crewai-tools - - - -

3.9 slim (glibc) mcp - - - -

3.9 slim (glibc) crewai - - - -

3.9 slim (glibc) crewai-tools - - - -

Imports

Agent, Task, Crew
wrong
```
from crewai import *
```
correct
```
from crewai import Agent, Task, Crew, Process
from crewai import LLM
```
Core classes are in the crewai package. Tools (SerperDevTool etc.) are in the separate crewai_tools package.
crewai_tools
wrong
```
from crewai import SerperDevTool
```
correct
```
from crewai_tools import SerperDevTool, FileReadTool
```
crewai_tools is a separate pip package. It is NOT included with pip install crewai.

Quickstart stale last tested: 2026-05-11

Minimal two-agent crew with sequential process

from crewai import Agent, Task, Crew, Process

researcher = Agent(
    role='Senior Researcher',
    goal='Uncover groundbreaking technologies in AI',
    backstory='You are an expert researcher with a passion for AI innovation.',
    verbose=True
)

writer = Agent(
    role='Tech Writer',
    goal='Craft compelling articles about AI discoveries',
    backstory='You are a skilled writer who makes complex topics accessible.',
    verbose=True
)

research_task = Task(
    description='Research the latest breakthroughs in AI for 2026.',
    expected_output='A list of 5 key AI breakthroughs with brief descriptions.',
    agent=researcher
)

write_task = Task(
    description='Write a short article based on the research findings.',
    expected_output='A 3-paragraph article in markdown format.',
    agent=writer
)

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    process=Process.sequential,
    verbose=True
)

result = crew.kickoff()
print(result)