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

@task: Reference Guide

By DevShelfHub

Marks a CrewBase method whose return value is a Task — registers it in the crew's task list.

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

What is @task?

Methods decorated with @task are how CrewBase discovers the Task objects that make up a Crew. Each decorated method typically returns Task(...) built from a row in tasks.yaml plus the agent returned by a sibling @agent method (for example self.researcher()). Discovery preserves source order, which maps to execution order when you use Process.sequential; for hierarchical crews, the manager still sees the same ordered list while delegating work.

The important contract is data flow: downstream tasks should receive upstream output through Task's context= parameter (a list of Task instances), not by calling another @task method from Python to synchronously pull a return value. That keeps kickoff semantics, retries, and tracing aligned with CrewAI's runtime. You can still branch logic inside the method body when constructing the Task, but the graph of dependencies lives on the Task objects themselves.

In tests, @task methods are convenient seams: you can swap tasks_config paths, stub agents, or assert that context wiring matches expectations without booting the full Crew. In production, keep task descriptions templated with clear placeholders so kickoff(inputs=...) can supply user-specific values consistently across environments.

When to Use

With @CrewBase. Every task the crew runs should be a @task method.

Use Cases

  • • Multi-step pipelines
  • • YAML-driven task definition
  • • Reusable task templates

Key Features

  • ✓ Auto-discovery
  • ✓ Order preservation
  • ✓ Works with tasks.yaml
  • ✓ Hooks into Task.context dependencies

When NOT to Use

When tasks must be constructed dynamically from external state — build them in code instead.

Notes

Order vs. real dependencies

Sequential process runs tasks in list order, but if task B needs task A's output, you still must set context= explicitly. Do not rely on declaration order alone when agents need prior artifacts.

Kickoff inputs and templates

Descriptions in YAML often use {topic}-style placeholders. Those resolve from the inputs dict passed to kickoff; mismatched keys surface late as empty strings, so validate inputs in @before_kickoff when schemas are strict.

Hierarchical crews

Manager-led processes still consume the same self.tasks collection. Keep manager-facing tasks explicit in YAML so delegation goals stay auditable and you avoid hidden coupling inside Python-only Task literals.

Testing and fixtures

Point tasks_config at a temp YAML file in tests, or patch agents_config, to isolate a single @task without network calls. Avoid mutating class-level paths across parallel tests without resetting CrewBase state.

Import

python 
from crewai.project import task

How to Apply

python 
@task
def research(self) -> Task:
    return Task(config=self.tasks_config['research'], agent=self.researcher())

What It Enables

  • ✓ Ordered execution
  • ✓ Context wiring
  • ✓ Test isolation

Code Examples

Research task

python 
@task
def research(self) -> Task:
    return Task(config=self.tasks_config['research'], agent=self.researcher())

Writer with context from research

python 
@task
def write(self) -> Task:
    return Task(
        config=self.tasks_config['write'],
        agent=self.writer(),
        context=[self.research()],
    )

Guarded output with expected_output

python 
@task
def summarize(self) -> Task:
    return Task(
        config=self.tasks_config['summarize'],
        agent=self.analyst(),
        output_json=SummaryModel,
    )

Integration Patterns

Inside @CrewBase class
Referenced from @crew via self.tasks

Common Mistakes

❌ Calling another @task method to chain output

✅ Pass context=[self.previous_task()] to receive its output via Task.context.

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

@task FAQ

What is @task in CrewAI?

Marks a CrewBase method whose return value is a Task — registers it in the crew's task list. Methods decorated with @task are how CrewBase discovers the Task objects that make up a Crew. Each decorated method typically returns Task(...) built from a row in tasks.yaml plus the agent returned by a sibling @agent method (for example self.researcher()). Discovery preserves source order, which maps to execution order when you use Process.sequential; for hierarchical crews, the manager still sees the same ordered list while delegating work. The important contract is data …

Which module defines the CrewAI decorator @task?

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

When should I use @task?

With @CrewBase. Every task the crew runs should be a @task method.

When should I avoid @task?

When tasks must be constructed dynamically from external state — build them in code instead.

How do I apply @task in Python?

@task def research(self) -> Task: return Task(config=self.tasks_config['research'], agent=self.researcher())

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.