DS DevShelfHub Projects · AI tools
Tutorials / CrewAI / Reference / Decorators / @CrewBase
Decorator crewai.project

@CrewBase: Reference Guide

By DevShelfHub

Class decorator that converts a Python class into a CrewAI scaffold with YAML config and decorator-driven discovery.

See the CrewAI API reference index, CrewAI introduction, hooks and events tutorial, and core concepts for surrounding context.

What is @CrewBase?

Applying @CrewBase to a class turns it into the canonical CrewAI project shape: class attributes point to agents.yaml and tasks.yaml, while methods decorated with @agent, @task, @crew, @before_kickoff, and @after_kickoff register automatically. The decorator hydrates self.agents_config / self.tasks_config, wires discovery order, and exposes the ergonomic self.agents / self.tasks collections consumed inside @crew — so Python remains the integration layer while YAML stays the business-readable spec.

This pattern shines when multiple contributors edit prompts without touching orchestration code, and when CI validates YAML schemas independently. For notebooks or demos, the same APIs work without @CrewBase, but you lose the single place where hook registration and config loading happen.

Version upgrades should re-run `crewai create crew` diffs: template paths, new hook decorators, and security defaults evolve. Keep custom logic in plain methods or mixins rather than forking generated files wholesale so merges stay tractable.

When to Use

Whenever you scaffold a project with `crewai create crew` — that's the default layout.

Use Cases

  • • Project scaffolds
  • • YAML-driven crews
  • • Larger applications with several crews

Key Features

  • ✓ Loads YAML config
  • ✓ Discovers @agent/@task methods
  • ✓ Provides agents_config & tasks_config

When NOT to Use

In a Jupyter notebook tutorial where one big function is clearer than a class.

Notes

Relative paths

YAML paths resolve relative to the working directory at kickoff. Containerize with explicit WORKDIR or absolute paths to avoid silent empty configs.

Multiple crews

Split separate products into separate @CrewBase classes rather than multiplexing one class with giant if/else blocks — discovery order becomes hard to reason about.

Testing

Point agents_config to fixture YAML in pytest, or monkeypatch the class attributes before instantiating the crew object.

Import

python 
from crewai.project import CrewBase

How to Apply

python 
@CrewBase
class MyCrew:
    agents_config = 'config/agents.yaml'
    tasks_config = 'config/tasks.yaml'

What It Enables

  • ✓ Project-style crews
  • ✓ YAML/code separation
  • ✓ Testing-friendly class structure

Code Examples

Skeleton

python 
@CrewBase
class ResearchCrew:
    agents_config = 'config/agents.yaml'
    tasks_config = 'config/tasks.yaml'

    @agent
    def researcher(self) -> Agent: ...

Hooks alongside decorators

python 
@CrewBase
class OpsCrew:
    agents_config = 'config/agents.yaml'
    tasks_config = 'config/tasks.yaml'

    @before_kickoff
    def validate(self, inputs):
        assert inputs.get('ticket')
        return inputs

    @after_kickoff
    def persist(self, output):
        save_ticket(output.raw)
        return output

Environment-specific YAML

python 
import os

@CrewBase
class ConfigurableCrew:
    agents_config = f"config/agents.{os.getenv('APP_ENV', 'dev')}.yaml"
    tasks_config = 'config/tasks.yaml'

Integration Patterns

YAML files in config/
@agent + @task + @crew methods

Common Mistakes

❌ Forgetting to set agents_config / tasks_config paths

✅ Provide the YAML paths as class attributes.

Related: Task class reference, Agent class reference, and the first Crew tutorial.

@CrewBase FAQ

What is @CrewBase in CrewAI?

Class decorator that converts a Python class into a CrewAI scaffold with YAML config and decorator-driven discovery. Applying @CrewBase to a class turns it into the canonical CrewAI project shape: class attributes point to agents.yaml and tasks.yaml, while methods decorated with @agent, @task, @crew, @before_kickoff, and @after_kickoff register automatically. The decorator hydrates self.agents_config / self.tasks_config, wires discovery order, and exposes the ergonomic self.agents / self.tasks collections consumed inside @crew — so Python remains the integration layer while YAML stays the b…

Which module defines the CrewAI decorator @CrewBase?

DevShelfHub maps @CrewBase to Python module crewai.project. Pin your installed crewai version and match imports to the import snippet on this page.

When should I use @CrewBase?

Whenever you scaffold a project with `crewai create crew` — that's the default layout.

When should I avoid @CrewBase?

In a Jupyter notebook tutorial where one big function is clearer than a class.

How do I apply @CrewBase in Python?

@CrewBase class MyCrew: agents_config = 'config/agents.yaml' tasks_config = 'config/tasks.yaml'

Where can I explore more CrewAI API reference pages?

Open the CrewAI API reference index on DevShelfHub to search classes, methods, and decorators, each with runnable examples, parameters, common mistakes, and cross-links.