Getting Started with CrewAI
CrewAI requires Python 3.10 or higher. Before starting, verify your Python version by running python --version in your terminal. If you need to upgrade, install the latest Python from python.org or use a version manager like pyenv. Using a virtual environment is strongly recommended to avoid dependency conflicts with other Python projects on your system. Create one with python -m venv crewai-env and activate it before installing CrewAI.
Install CrewAI
Install CrewAI using pip: pip install crewai. This installs the core framework, the CLI tool, and all required dependencies. For projects that need additional tool integrations, install the tools extras: pip install crewai[tools]. This adds pre-built tools for web search, file operations, and other common agent capabilities.
Verify the installation by running crewai version in your terminal. This should display the installed version number. If the command is not found, ensure your Python scripts directory is in your system PATH. On macOS and Linux, this is typically ~/.local/bin or the bin directory of your active virtual environment.
If you encounter installation errors related to specific dependencies (particularly around vector database libraries), ensure you have a C compiler installed on your system. On macOS, install Xcode Command Line Tools with xcode-select --install. On Ubuntu or Debian, install build-essential with sudo apt install build-essential. These tools are needed to compile certain Python packages that CrewAI depends on.
Scaffold a New Project
Use the CrewAI CLI to generate a project template: crewai create crew my-project. This creates a directory structure with configuration files for agents (agents.yaml), tasks (tasks.yaml), and the main Python file that assembles everything into a crew.
The scaffolded project includes sensible defaults that you can modify. The agents.yaml file contains a sample agent definition with role, goal, and backstory fields. The tasks.yaml file contains a sample task with description and expected output. The crew.py file imports these configurations and assembles them into a runnable crew.
Navigate to the project directory: cd my-project. The project structure separates configuration from code, making it easy to modify agent behavior without changing Python logic. This separation also makes it possible for non-developers to adjust agent prompts and task descriptions by editing YAML files, which is valuable for teams where domain experts contribute to agent design.
Configure Your LLM API Key
CrewAI needs an API key to communicate with your chosen LLM provider. Set the appropriate environment variable for your provider. For OpenAI: export OPENAI_API_KEY=your-key-here. For Anthropic: export ANTHROPIC_API_KEY=your-key-here. For Azure OpenAI, you need both the API key and the endpoint URL as environment variables.
For persistent configuration, add the export command to your shell profile (.bashrc, .zshrc) or use a .env file in your project directory. CrewAI automatically reads from .env files when present, which keeps API keys out of your code and version control. Add .env to your .gitignore file to prevent accidentally committing secrets.
By default, CrewAI uses OpenAI GPT-4. To change the default model, set the OPENAI_MODEL_NAME environment variable or specify the model directly in your agent configuration. For Anthropic models, set the model parameter on each agent to the desired Claude model identifier. Using a less expensive model like GPT-3.5-turbo or Claude Haiku during development saves money while you iterate on agent design and task descriptions.
Define Your Agents
Open agents.yaml and define your agents. Each agent needs three required fields: role (the agent specialization), goal (what it should accomplish), and backstory (context that shapes its reasoning). A simple research agent might have role "Research Analyst," goal "Find accurate, relevant information on the given topic," and a backstory describing its expertise and approach.
For a minimal two-agent crew, define a researcher and a writer. The researcher gathers information, and the writer transforms that information into a structured output. This pattern is the most common starting point for CrewAI projects and demonstrates the core value of multi-agent collaboration.
The backstory field deserves special attention because it significantly affects agent output quality. A vague backstory like "You are an expert" produces generic results. A specific backstory that describes the agent experience, methodology, and quality standards produces focused, higher-quality output. For example, a research agent backstory might describe its preference for primary sources, its habit of cross-referencing multiple sources, and its focus on recent publications.
Optional parameters include allow_delegation (whether the agent can assign subtasks to others), verbose (whether to log detailed execution information), max_iter (maximum reasoning iterations per task), and llm (the specific model to use for this agent). Start with verbose=True during development so you can see exactly what each agent is doing.
Create Your Tasks
Open tasks.yaml and define tasks for each agent. Each task needs a description (what needs to be done), expected_output (what the output should look like), and agent (which agent handles this task). Tasks execute in the order they are defined when using sequential processing.
The task description is the single most important quality lever. Vague descriptions produce vague results. Be specific about what information to gather, what format to use, what criteria to apply, and what the output should contain. Include examples of desired output format when possible. A description like "Research the topic" will produce poor results compared to "Find five recent developments in the topic area, each with the source, date, key finding, and practical implications for businesses."
For structured output, define a Pydantic model in your Python code and reference it as the task output_pydantic parameter. This ensures the agent output conforms to a specific schema, making downstream processing reliable. Pydantic output is particularly valuable when the crew results feed into other software systems that expect consistent data structures.
Task dependencies are implicit in sequential mode: each task can access the output of all previous tasks through its context. In some cases, you may want a task to only reference specific previous tasks rather than the entire history. Use the context parameter to explicitly list which tasks should provide context, which keeps prompts focused and reduces token consumption.
Assemble and Run the Crew
The main crew.py file brings agents and tasks together. The scaffolded code imports the YAML configurations, creates Agent and Task objects, assembles them into a Crew with a specified process type (sequential by default), and provides a run method that calls crew.kickoff().
Run the crew: crewai run. This executes the workflow, showing agent activity in the terminal if verbose mode is enabled. The final output is the result of the last task in the sequence. Watch the verbose output to understand how each agent interprets its role and processes its task. This is where you will identify opportunities to improve agent definitions and task descriptions.
To pass input to the crew at runtime, use the inputs parameter: crew.kickoff(inputs={"topic": "artificial intelligence trends"}). Input variables can be referenced in task descriptions using curly brace notation: "Research the latest developments in {topic}." This makes your crew reusable across different inputs without modifying the configuration files.
Troubleshooting Common Issues
The most common first-run issue is an API key error, which produces a message about authentication failure or invalid credentials. Double-check that your environment variable name matches your provider exactly and that the key value has no leading or trailing whitespace. If using a .env file, verify that CrewAI is reading it by adding a print statement before crew.kickoff() that checks os.environ for the key.
Rate limit errors occur when your crew sends too many requests to the LLM provider in a short period. This is common with crews that have many agents or tasks. Add a rate limiter or implement exponential backoff in your configuration. Some teams reduce this issue by using a faster, cheaper model for less critical agents while reserving the premium model for agents that require the highest quality reasoning.
Next Steps After Your First Crew
Once your first crew runs successfully, several enhancements are worth exploring. Enable memory by adding memory=True to your crew configuration to let agents retain context across tasks. Add tools to give agents capabilities beyond text generation, such as web search or file reading. Experiment with different process types (hierarchical, consensual) to see how they affect agent collaboration.
Try adding a third agent that reviews or validates the output of the first two. This quality-check pattern is common in production crews and demonstrates how additional agents can improve output reliability. Monitor token consumption in these experiments to understand the cost implications of different crew configurations.
CrewAI from installation to working prototype is a single-session activity. Start with two agents (researcher and writer), use specific task descriptions with concrete output expectations, and iterate from there. The scaffolded project template gives you a working foundation to customize.