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

Task: Reference Guide

By DevShelfHub

A unit of work executed by an Agent — described in natural language with an expected output contract.

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

What is Task?

Task is the atomic scheduling unit in CrewAI: every kickoff walks a graph of Task objects, each bound to an Agent (or left None so a hierarchical manager can assign work). The description and expected_output strings are not decorative — they are the primary contract the LLM sees, so vague wording directly translates into vague artifacts. context= wires upstream TaskOutput text into downstream prompts; async_execution=True lets independent branches overlap when the process allows it; human_input=True inserts an operator checkpoint before the task is marked complete.

Structured outputs sit on the same object: output_pydantic and output_json coerce the model into machine-parseable shapes, while markdown and output_file control presentation and persistence. Guardrails attach at task scope so expensive validation only runs where outputs are high risk. Understanding Task is prerequisite material for Crew, Process, and Flow tutorials because every orchestration mode ultimately reduces to "which Task runs next, with what context".

When to Use

Every distinct step the crew performs — research, draft, critique, transform, or gate — whenever you need a named output artifact.

Use Cases

  • • Research step
  • • Drafting step
  • • Review step
  • • Approval step
  • • Parallel research branches
  • • Typed extraction into Pydantic models

Key Features

  • ✓ Natural-language description
  • ✓ Typed outputs
  • ✓ Guardrails
  • ✓ Async/Human-input flags
  • ✓ context dependency graph
  • ✓ Per-task tool overrides

When NOT to Use

Cross-cutting telemetry or policy that should fire on every LLM exchange — prefer crew-level hooks and event listeners instead of duplicating logic across tasks.

Notes

expected_output is your QA spec

Treat it like a test assertion in prose: cite format (Markdown vs plain), length bounds, required sections, and citation rules. Changing only the description while leaving expected_output generic is the most common source of unusable crew outputs.

context ordering and token cost

Each upstream TaskOutput is injected wholesale. Long research tasks feeding many dependents can blow context windows — summarize in an intermediate task or trim in a callback before downstream agents see the text.

async_execution vs Flow

async_execution parallelizes within Crew scheduling rules; it does not replace arbitrary DAGs or human gates mid-branch. When ordering assumptions get fragile, move branching to Flow and call crews from stable @listen handlers.

Guardrail retries and spend

guardrail_max_retries re-invokes the LLM after failed validation. Pair tight guardrails with smaller models or lower temperature to avoid runaway token spend when outputs repeatedly miss the bar.

Import

python 
from crewai import Task

Key Parameters

Parameter Type Default Purpose
description str — What the agent should do.
expected_output str '' Shape/style of the expected result.
agent Agent | None None Who runs the task. None = manager-assigned in hierarchical.
name str | None None Task identifier.
tools list[BaseTool] [] Tools available for this task only.
context list[Task] | None None Upstream tasks whose outputs feed this one.
async_execution bool False Run this task concurrently.
human_input bool False Prompt the user for review before completing.
markdown bool False Format output as Markdown.
output_file str | None None Path to write the output.
output_json type[BaseModel] | None None Force JSON-shaped output.
output_pydantic type[BaseModel] | None None Force Pydantic-parsed output.
callback Callable | None None Post-task hook.
guardrail Callable | None None Single output validator.
guardrails list[Callable] | None None Multiple validators.
guardrail_max_retries int 3 Validation retry budget.

Code Examples

Pydantic-typed extraction

python 
from pydantic import BaseModel
from crewai import Task

class Profile(BaseModel):
    name: str
    summary: str

profile_task = Task(
    description='Research {company} and return a concise profile.',
    expected_output='A Profile model with factual strings only.',
    agent=researcher,
    output_pydantic=Profile,
)

Context chain across three tasks

python 
from crewai import Task

outline = Task(description='Outline the article on {topic}', expected_output='H2/H3 outline', agent=outliner)
draft = Task(description='Write the article', expected_output='800+ word Markdown', agent=writer, context=[outline])
polish = Task(description='Copy-edit for tone', expected_output='Final Markdown', agent=editor, context=[draft])

Async parallel research with merge

python 
from crewai import Task

a = Task(description='Research market size', agent=r1, async_execution=True, expected_output='Bullets')
b = Task(description='Research regulation', agent=r2, async_execution=True, expected_output='Bullets')
merge = Task(description='Merge into one brief', agent=lead, context=[a, b], expected_output='<= 400 words')

Common Mistakes

❌ Vague expected_output

✅ Be explicit: 'A 200-word Markdown summary with sources'.

❌ Using the same Task object twice in incompatible context graphs

✅ Instantiate separate Task objects when you need parallel branches with different dependencies.

Task FAQ

What is Task in CrewAI?

A unit of work executed by an Agent — described in natural language with an expected output contract. Task is the atomic scheduling unit in CrewAI: every kickoff walks a graph of Task objects, each bound to an Agent (or left None so a hierarchical manager can assign work). The description and expected_output strings are not decorative — they are the primary contract the LLM sees, so vague wording directly translates into vague artifacts. context= wires upstream TaskOutput text into downstream prompts; async_execution=True lets independent branches overlap when the process all…

Which package defines the CrewAI class Task?

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

When should I use Task?

Every distinct step the crew performs — research, draft, critique, transform, or gate — whenever you need a named output artifact.

When should I avoid using Task?

Cross-cutting telemetry or policy that should fire on every LLM exchange — prefer crew-level hooks and event listeners instead of duplicating logic across tasks.

How do I import Task in Python?

from crewai import Task

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.