DS DevShelfHub Projects · AI tools
Tutorials / CrewAI / Reference / Classes / CrewBase
Class core

CrewBase: Reference Guide

By DevShelfHub

Decorator/class scaffold that combines YAML config with @agent/@task/@crew methods into a tidy project layout.

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

What is CrewBase?

CrewBase is the decorator returned by `from crewai.project import CrewBase` that turns a plain Python class into a CrewAI project entrypoint. You declare agents_config and tasks_config as class attributes pointing at YAML files, then implement @agent / @task / @crew methods that hydrate Agent and Task objects from those configs. Optional @before_kickoff and @after_kickoff hooks run around kickoff so you can normalize inputs, attach tracing, or persist CrewOutput without scattering glue code across notebooks.

Compared with imperative Crew(...) literals, CrewBase shines when multiple engineers edit agent prompts and task contracts in YAML while application engineers keep wiring, secrets, and deployment concerns in Python. The decorator registers factories so the CLI (`crewai run`) and AMP deployments can discover your crew without import-time side effects beyond reading YAML paths.

The mental model is still one Crew per decorated class: the @crew method typically returns Crew(agents=self.agents, tasks=self.tasks, ...). Keep that method thin — heavy business logic belongs in Flows, tools, or plain functions the tasks call — so YAML edits stay reviewable and tests stay fast.

When to Use

Project scaffolds — the `crewai create crew` default.

Use Cases

  • • Standardized project layouts
  • • Larger applications

Key Features

  • ✓ YAML loading
  • ✓ Decorator registration
  • ✓ Re-runnable class instances

When NOT to Use

One-off notebooks where direct Crew/Agent literals are clearer.

Notes

YAML paths are resolved relative to the package

Broken paths fail at import or first kickoff with file-not-found errors that look like CrewAI bugs. Keep configs under version control next to the decorated module and add CI checks that parse the YAML.

Decorator order matters

Apply @CrewBase as the outermost class decorator before framework-specific mixins that mutate attributes CrewBase expects. Reordering decorators can silently skip agent registration.

Do not hide secrets in YAML

Treat YAML as prompt and task metadata, not a vault. Read API keys from the environment inside @agent methods or your process manager, then inject them into tools rather than storing literals in agents.yaml.

Testing strategy

Unit-test YAML parsing separately from LLM calls: load configs with pydantic or ruamel, assert required keys, and only integration-test the decorated class against recorded fixtures or mocked LLMs.

Import

python 
from crewai.project import CrewBase

Code Examples

Minimal class with YAML paths

python 
from crewai.project import CrewBase, agent, task, crew
from crewai import Agent, Task, Crew, Process

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

    @agent
    def researcher(self) -> Agent:
        return Agent(config=self.agents_config['researcher'])

    @task
    def research_task(self) -> Task:
        return Task(config=self.tasks_config['research_task'])

    @crew
    def crew(self) -> Crew:
        return Crew(agents=self.agents, tasks=self.tasks, process=Process.sequential)

Kickoff hook logging inputs

python 
from crewai.project import CrewBase, before_kickoff

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

    @before_kickoff
    def log_inputs(self, inputs):
        print('kickoff inputs keys:', sorted(inputs.keys()))
        return inputs

After kickoff persistence sketch

python 
from crewai.project import CrewBase, after_kickoff

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

    @after_kickoff
    def save_output(self, output):
        # Replace with your warehouse write
        print('token_usage:', output.token_usage)
        return output

Common Mistakes

❌ Forgetting to set agents_config / tasks_config

✅ Set the YAML paths as class attributes.

❌ Returning a new Crew instance on every property access

✅ Construct inside @crew once per lifecycle or memoize so agents/tasks lists stay stable across kicks.

CrewBase FAQ

What is CrewBase in CrewAI?

Decorator/class scaffold that combines YAML config with @agent/@task/@crew methods into a tidy project layout. CrewBase is the decorator returned by `from crewai.project import CrewBase` that turns a plain Python class into a CrewAI project entrypoint. You declare agents_config and tasks_config as class attributes pointing at YAML files, then implement @agent / @task / @crew methods that hydrate Agent and Task objects from those configs. Optional @before_kickoff and @after_kickoff hooks run around kickoff so you can normalize inputs, attach tracing, or persist CrewOutput without scatt…

Which package defines the CrewAI class CrewBase?

DevShelfHub maps CrewBase to Python module crewai.project (package path crewai.project in this reference). Pin your installed crewai version and match imports to the snippet on this page.

When should I use CrewBase?

Project scaffolds — the `crewai create crew` default.

When should I avoid using CrewBase?

One-off notebooks where direct Crew/Agent literals are clearer.

How do I import CrewBase in Python?

from crewai.project import CrewBase

Where can I explore more CrewAI API reference pages?

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