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

@before_kickoff: Reference Guide

By DevShelfHub

Registers a method to run before Crew.kickoff() — typical place for input validation, prep, or setup.

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

What is @before_kickoff?

Methods decorated with @before_kickoff execute once per kickoff before any task starts. They receive the inputs dict Crew.kickoff forwarded, and may mutate it, replace it entirely by returning a new dict, or abort early by raising a validation error. This is the right layer for schema checks, default injection, feature-flag resolution, and attaching tracing IDs that downstream tasks read via placeholders.

Unlike per-step callbacks, @before_kickoff is crew-wide — anything expensive you do here blocks the whole run, so keep remote fetches bounded or move them into tools. Multiple @before_kickoff methods can exist; assume framework-defined ordering and avoid depending on side-effect sequencing between them.

Pair with @after_kickoff for symmetrical teardown: initialize clients here, flush metrics there. When integrating with FastAPI or Celery, translate request payloads into the dict shape your YAML expects so tasks can keep using {topic}-style interpolation without bespoke glue in every @task method.

When to Use

Validating inputs, hydrating context, setting up tracing.

Use Cases

  • • Validate user input
  • • Initialize external clients
  • • Log start of run

Key Features

  • ✓ Runs once per kickoff
  • ✓ Can mutate inputs
  • ✓ Multiple methods supported

When NOT to Use

Per-task work — use Task.callback or step_callback for finer hooks.

Notes

Return the dict

Returning None leaves inputs unchanged in most versions, but returning an explicit dict is clearer when you mutate a copy — future readers see the contract immediately.

Secrets

Do not log raw inputs that may contain API keys. Redact before printing and keep sensitive fields out of YAML templates that might echo into traces.

Idempotency

Kickoff may retry after partial failures in higher-level orchestrators. Hooks that append side effects (duplicate CRM rows) should key off a stable run_id.

Import

python 
from crewai.project import before_kickoff

How to Apply

python 
@before_kickoff
def prep(self, inputs):
    inputs['ts'] = time.time()
    return inputs

What It Enables

  • ✓ Setup phase
  • ✓ Input validation
  • ✓ Tracing initialization

Code Examples

Validate inputs

python 
@before_kickoff
def prep(self, inputs):
    if not inputs.get('topic'):
        raise ValueError('topic is required')
    return inputs

Inject tracing metadata

python 
import uuid

@before_kickoff
def trace(self, inputs):
    inputs = dict(inputs)
    inputs.setdefault('run_id', str(uuid.uuid4()))
    return inputs

Normalize legacy keys

python 
@before_kickoff
def alias(self, inputs):
    merged = dict(inputs)
    if 'q' in merged and 'topic' not in merged:
        merged['topic'] = merged['q']
    return merged

Integration Patterns

Inside @CrewBase class
Pairs with @after_kickoff

Common Mistakes

❌ Returning None when you wanted to mutate inputs

✅ Return the (possibly mutated) inputs dict.

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

@before_kickoff FAQ

What is @before_kickoff in CrewAI?

Registers a method to run before Crew.kickoff() — typical place for input validation, prep, or setup. Methods decorated with @before_kickoff execute once per kickoff before any task starts. They receive the inputs dict Crew.kickoff forwarded, and may mutate it, replace it entirely by returning a new dict, or abort early by raising a validation error. This is the right layer for schema checks, default injection, feature-flag resolution, and attaching tracing IDs that downstream tasks read via placeholders. Unlike per-step callbacks, @before_kickoff is crew-wide — anything exp…

Which module defines the CrewAI decorator @before_kickoff?

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

When should I use @before_kickoff?

Validating inputs, hydrating context, setting up tracing.

When should I avoid @before_kickoff?

Per-task work — use Task.callback or step_callback for finer hooks.

How do I apply @before_kickoff in Python?

@before_kickoff def prep(self, inputs): inputs['ts'] = time.time() return inputs

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.