CrewAI Core Concepts

CrewAI is an open‑source framework that helps you design flows and crews so multiple AI agents can solve complex, real-world tasks in a structured, production‑ready way

1. What CrewAI Is

• CrewAI is an open‑source framework for orchestrating autonomous AI agents and building complex workflows
• It focuses on multi‑agent collaboration, so different agents with different roles can work together like a digital team
• The framework is designed for production use: long‑running processes, reliability, observability, and integration with other systems

2. Core Architecture: Flows and Crews

CrewAI’s mental model: a Flow is the manager, a Crew is the team.

2.1 Flows: The Backbone

• A Flow defines the overall process: steps, control logic, and how data moves through the system
• Flows handle state management (remembering data between steps and runs) and event‑driven execution (reacting to triggers or external inputs)
• You can add control flow such as conditionals, loops, and branching to encode complex business logic safely

2.2 Crews: The Intelligence

• A Crew is a group of specialized agents that collaborate to solve a specific task inside a Flow.
• Each agent has a role, a goal, and access to specific tools (APIs, databases, internal utilities) it can use autonomously
• Crews support task delegation and internal coordination: agents can share information and divide work to reach a shared objective.

2.3 How Flows and Crews Work Together

• The Flow starts a process or responds to an event (for example, an API request or a schedule trigger)
• The Flow manages state and decides when to call a Crew for a complex, open‑ended task
• The Crew’s agents collaborate to produce a result, which is returned to the Flow so it can continue execution (e.g., store data, call another service, or trigger another step)

3. When to Use Flows vs Crews

In practice, you almost always use both together

• Use a Flow to:

  • Define the end‑to‑end process, state, and business logic.
  • Manage triggers (events, webhooks, schedules) and responses.
  • Orchestrate multiple Crews or simple Python steps in sequence

• Use a Crew to:

  • Handle complex, creative, or uncertain tasks (research, writing, planning, code suggestions)
  • Let agents reason, collaborate, and decide which tools to call.
  • Encapsulate a “team skill” that your Flow can reuse in different contexts

Typical patterns:

• Simple automation: Single Flow with Python tasks (no Crew needed).
• Complex research: Flow manages state → Crew performs research
• Application backend: Flow handles API requests → Crew generates content → Flow saves to DB

4. Why CrewAI Is Useful

• Autonomous operation: Agents can make local decisions based on their role, tools, and objectives, reducing manual prompting
• Natural interaction: Agents communicate in natural language and coordinate like human teammates, which makes behavior easier to reason about
• Extensibility: You can plug in any API, database, or local tool as a capability for agents
• Production‑readiness: Built with reliability, scalability, and observability in mind for real‑world workloads
• Security and cost: Supports enterprise security practices and aims to minimize token usage and API calls

5. Installation Prerequisites

Before installing CrewAI locally, you must satisfy some environment requirements

• Python version: Python must be between 3.10 (inclusive) and 3.14 (exclusive)
• OpenAI SDK: CrewAI 0.175.0 requires openai >= 1.13.3 if you manage dependencies yourself
• Dependency manager: CrewAI uses uv as its dependency and package management tool to simplify setup and execution

NOTE: the Maven Editor describes the code blocks as JavaScript but these are NOT JavaScript code snippets - please ignore that label

To check your Python version:

python3 --version

If you need a new Python version, download it from python.org or your OS package manager

6. Installing uv

CrewAI leans on uv for tool and project management

On macOS / Linux bash terminal (with curl)

curl -LsSf https://astral.sh/uv/install.sh | sh

If you do not have curl, you can use wget instead

wget -qO- https://astral.sh/uv/install.sh | sh

On Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

7. Installing the CrewAI CLI

Once uv is installed, you can install the CrewAI CLI tool

• Install the CLI:

uv tool install crewai

• Verify that it worked

uv tool list

You should see an entry like: crewai v0.102.0 - crewai.

• To upgrade to the latest version

uv tool install crewai --upgrade

8. Creating a New CrewAI Project

CrewAI encourages a structured, YAML‑first project layout for agents and tasks

1. Generate project scaffolding

   crewai create crew <your_project_name>

2. This creates a folder like my_project/ with a structure similar to

   my_project/
   ├── .gitignore
   ├── knowledge/
   ├── pyproject.toml
   ├── README.md
   ├── .env
   └── src/
   	└── my_project/
   	├── __init__.py
   	├── main.py
   	├── crew.py
   	├── tools/
   	│ 	├── custom_tool.py
   	│ 	└── __init__.py
   	└── config/
   		├── agents.yaml
   		└── tasks.yaml

3. Key files and directories

   • agents.yaml: Define your agents, their roles, goals, and tools.
   • tasks.yaml: Describe tasks, workflows, and which agent does what.
   • .env: Store API keys and other secrets (never commit this file).
   • main.py: Entry point to run your Flow or Crew from code.
   • crew.py: Orchestration logic that wires agents, tasks, and flows together.
   • tools/: Custom Python tools that agents can call.
   • knowledge/: Your knowledge base files (docs, FAQs, etc.).

9. Running Your Crew Locally

After customizing agents and tasks, you install dependencies and run the project

• Install dependencies (from the project root):

crewai install

• Add extra Python packages if needed

uv add <package-name>

• Run your crew

crewai run

This will execute the entry flow and crew definitions inside your project and print results in your terminal

10. Enterprise Options (No Local Setup)

If you do not want to manage infrastructure, CrewAI offers hosted options

• CrewAI AMP (SaaS):

  • No local installation required; you sign up at app.crewai.com and build Crews in a managed environment
  • Automatic updates, managed scaling, and enterprise features like environments and observability

• CrewAI Factory (Self‑hosted):

  • Containerized deployment you can run on any major cloud or on‑prem infrastructure
  • Integrates with your existing security stack and internal systems

These options are useful when you are building mission‑critical, multi‑team automations and want centralized control, governance, and monitoring