design-task

CrewAI Task Design Guide

How to write effective tasks that produce reliable, high-quality output from your agents.

The 80/20 Rule

Spend 80% of your effort on task design, 20% on agent design. The task is the most important lever you have. A well-designed task with a mediocre agent will outperform a poorly designed task with an excellent agent.

1. Anatomy of an Effective Task

Every task needs two things: a description (what to do and how) and an expected_output (what the result looks like).

Description — The Instructions
A good description includes:

What to do — the core action

How to do it — specific steps or approach

Context — why this matters, what it feeds into

Constraints — scope limits, things to avoid

Inputs — what data or context is available

research_task:
  description: >
    Conduct thorough research about {topic} for the year {current_year}.

    Your research should:
    1. Identify the top 5 key trends and breakthroughs
    2. For each trend, find at least 2 credible sources
    3. Note any controversies or competing viewpoints
    4. Assess potential industry impact (high/medium/low)

    Focus on developments from the last 6 months.
    Do NOT include speculation or unverified claims.
    The output will feed into a report for {target_audience}.
  expected_output: >
    A structured research brief with 5 sections, one per trend.
    Each section includes: trend name, 2-3 paragraph summary,
    source citations, impact assessment (high/medium/low),
    and a confidence level for your findings.
  agent: researcher

Expected Output — The Success Criteria

The expected_output tells the agent what "done" looks like. Be specific about:

Format — bullet points, paragraphs, JSON, table

Structure — sections, headings, order

Length — approximate word count or number of items

Quality markers — citations required, confidence levels, specific fields

Bad Expected Output
Good Expected Output

A research report
A structured brief with 5 sections, each containing: trend name, 2-3 paragraph summary, source citations, and impact rating

An analysis of the data
A markdown table with columns: metric name, current value, 30-day trend, and recommended action. Include at least 10 metrics.

A blog post
A 1000-1500 word technical blog post with: title, introduction, 3-4 main sections with code examples, and a conclusion with next steps

2. The Single Purpose Principle

One task = one objective. Never combine multiple operations into a single task.

Bad: "God Task"

# DON'T do this — too many objectives in one task
research_and_write_task:
  description: >
    Research {topic}, analyze the findings, write a blog post,
    and proofread it for grammar errors.
  expected_output: >
    A polished blog post about {topic}.

Good: Focused Tasks

research_task:
  description: >
    Research {topic} and identify the top 5 key developments.
  expected_output: >
    A research brief with 5 sections covering key trends.
  agent: researcher

writing_task:
  description: >
    Using the research findings, write a technical blog post about {topic}.
  expected_output: >
    A 1000-1500 word blog post with introduction, main sections,
    and conclusion. Include code examples where relevant.
  agent: writer

editing_task:
  description: >
    Review and edit the blog post for grammar, clarity, and consistency.
  expected_output: >
    The final edited blog post with all corrections applied.
    Include a brief editor's note listing what was changed.
  agent: editor

Each task has one clear objective. The sequential flow passes context automatically.

3. Task Configuration Reference

Essential Parameters

Task(
    description="...",          # Required: what to do
    expected_output="...",      # Required: what the result looks like
    agent=researcher,           # Optional for hierarchical process; required for sequential
)

Task Dependencies with context

analysis_task = Task(
    description="Analyze the research findings...",
    expected_output="...",
    agent=analyst,
    context=[research_task],    # Receives research_task's output as context
)

In sequential process: Each task auto-receives all prior task outputs. Use context only when you need non-linear dependencies.

In hierarchical process: context is how you create explicit data flow between tasks.

Structured Output

Use output_pydantic or output_json when downstream code needs to parse the result:

from pydantic import BaseModel

class ResearchReport(BaseModel):
    trends: list[str]
    confidence: float
    sources: list[str]

research_task = Task(
    description="...",
    expected_output="A structured report with trends, confidence score, and sources.",
    agent=researcher,
    output_pydantic=ResearchReport,   # Agent's output is parsed into this model
)

Important: expected_output is always a string description — never a class name. The Pydantic model goes in output_pydantic, and the expected_output text tells the agent what fields to include.

Access structured output:

result = crew.kickoff(inputs={...})
last_task_output = result.pydantic          # Pydantic model from the last task
all_outputs = result.tasks_output           # List of all TaskOutput objects
first_task = all_outputs[0].pydantic        # Pydantic from a specific task

File Output

Task(
    ...,
    output_file="output/report.md",    # Save output to file
    create_directory=True,             # Create directory if missing (default: True)
)

File output and structured output can be combined — the file gets the raw text, and output_pydantic gets the parsed model.

Async Execution

Task(
    ...,
    async_execution=True,     # Run without blocking the next task
)

Use for tasks that can run in parallel. The crew continues to the next task while this one executes. Use context on downstream tasks to wait for async results.

Human Review

Task(
    ...,
    human_input=True,         # Pause for human review before finalizing
)

When enabled, the agent presents its result and waits for human feedback before marking the task complete. Use for critical outputs that need human approval.

Do not use human_input=True or Flow @human_feedback to model normal follow-up chat. In conversational Flows, the next user line should be another flow.handle_turn(message, session_id=...) call. Human review is for approving or correcting a specific task/step output before it moves downstream.

Markdown Formatting

Task(
    ...,
    markdown=True,            # Add markdown formatting instructions
)

Automatically instructs the agent to format output with proper markdown headers, lists, emphasis, and code blocks.

Callbacks

def log_completion(output):
    print(f"Task completed: {output.description[:50]}...")
    save_to_database(output.raw)

Task(
    ...,
    callback=log_completion,  # Called after task completion
)

4. Task Guardrails — Quality Control

Guardrails validate task output before it passes to the next step. If validation fails, the agent retries.

Function-Based Guardrails

def validate_word_count(output) -> tuple[bool, Any]:
    """Ensure output is between 500-2000 words."""
    word_count = len(output.raw.split())
    if word_count < 500:
        return (False, f"Output too short ({word_count} words). Expand to at least 500 words.")
    if word_count > 2000:
        return (False, f"Output too long ({word_count} words). Condense to under 2000 words.")
    return (True, output)

Task(
    ...,
    guardrail=validate_word_count,
    guardrail_max_retries=3,       # Max retry attempts (default: 3)
)

Return format: (bool, Any) — first element is pass/fail, second is the result (on success) or error message (on failure).

LLM-Based Guardrails

Task(
    ...,
    guardrail="Verify the output contains at least 3 source citations and no speculative claims.",
)

String guardrails use the agent's LLM to evaluate the output. Good for subjective quality checks.

Chaining Multiple Guardrails

Task(
    ...,
    guardrails=[
        validate_word_count,           # Function: check length
        validate_no_pii,               # Function: check for PII
        "Ensure the tone is professional and appropriate for a business audience.",  # LLM check
    ],
    guardrail_max_retries=3,
)

Guardrails execute sequentially. Each receives the output of the previous guardrail. Mix function-based (deterministic) and LLM-based (subjective) checks.

5. YAML Configuration (Recommended)

tasks.yaml

research_task:
  description: >
    Conduct thorough research about {topic} for {current_year}.
    Identify key trends, breakthrough technologies,
    and potential industry impacts.
    Focus on the last 6 months of developments.
  expected_output: >
    A structured research brief with 5 sections.
    Each section: trend name, 2-3 paragraph summary,
    source citations, and impact assessment.
  agent: researcher

analysis_task:
  description: >
    Analyze the research findings and create actionable recommendations
    for {target_audience}.
  expected_output: >
    A prioritized list of 5 recommendations with:
    rationale, estimated effort, and expected impact.
  agent: analyst
  context:
    - research_task

report_task:
  description: >
    Compile a final report combining research and analysis for {target_audience}.
  expected_output: >
    A polished markdown report with executive summary,
    detailed findings, recommendations, and appendices.
  agent: writer
  output_file: output/report.md

Wiring in crew.py

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

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

    @task
    def analysis_task(self) -> Task:
        return Task(
            config=self.tasks_config["analysis_task"],
            context=[self.research_task()],
        )

    @task
    def report_task(self) -> Task:
        return Task(
            config=self.tasks_config["report_task"],
            output_file="output/report.md",
        )

Critical: The method name (def research_task) must match the YAML key (research_task:).

6. Task Dependencies and Context Flow

Sequential Process (Default)

In Process.sequential, tasks run in order. Each task automatically receives all prior task outputs as context.

research_task → analysis_task → report_task
     ↓               ↓              ↓
  output 1    output 1 + 2    output 1 + 2 + 3

You don't need context= in sequential — it's implicit. Use it only to create non-linear dependencies:

# Task C depends on A but NOT B
task_c = Task(
    ...,
    context=[task_a],  # Only receives task_a output, not task_b
)

Explicit Dependencies

# Diamond dependency pattern
task_a = Task(...)                          # Entry point
task_b = Task(..., context=[task_a])        # Depends on A
task_c = Task(..., context=[task_a])        # Also depends on A
task_d = Task(..., context=[task_b, task_c])  # Depends on both B and C

Conditional Tasks

from crewai.task import ConditionalTask

def needs_more_data(output) -> bool:
    return len(output.pydantic.items) < 10

extra_research = ConditionalTask(
    description="Fetch additional data sources...",
    expected_output="...",
    agent=researcher,
    condition=needs_more_data,  # Only runs if previous output has < 10 items
)

7. Task Tools

Tasks can have their own tools that override the agent's default tools for that specific task:

from crewai_tools import SerperDevTool, ScrapeWebsiteTool

Task(
    description="Search for and scrape the top 5 articles about {topic}...",
    expected_output="...",
    agent=researcher,
    tools=[SerperDevTool(), ScrapeWebsiteTool()],  # Task-specific tools
)

When to use task-level tools:

The task needs tools the agent doesn't normally have

You want to restrict an agent to specific tools for this task

Different tasks by the same agent need different tool sets

8. Variable Interpolation

Use {variable} placeholders in YAML for reusable tasks:

research_task:
  description: >
    Research {topic} trends for {current_year},
    targeting {target_audience}.
  expected_output: >
    A report on {topic} suitable for {target_audience}.

Variables are replaced when you call crew.kickoff(inputs={...}):

crew.kickoff(inputs={
    "topic": "AI Agents",
    "current_year": "2025",
    "target_audience": "developers",
})

Common mistakes:

Missing variable in inputs → literal {variable} appears in the prompt

Using {{ }} Jinja2 syntax → crewAI uses single braces { }

Unused variables in inputs → silently ignored (no error)

9. Common Task Design Mistakes

Mistake
Impact
Fix

Vague description ("Research the topic")
Agent produces shallow, unfocused output
Add specific steps, constraints, and context

Vague expected_output ("A report")
Agent guesses at format and structure
Specify format, sections, length, quality markers

Multiple objectives in one task
Agent does all of them poorly
Split into focused single-purpose tasks

Modeling each chat turn as a Crew task
Tasks are batch/workflow units, not the conversational session loop
Use a conversational Flow and call handle_turn() per user message

No context between dependent tasks
Agent lacks information from prior steps
Use context=[prior_task] for explicit dependencies

expected_output references a Pydantic class
Agent sees a class name string, not field names
Keep expected_output as a human-readable string; use output_pydantic for the model

Missing tools for data tasks
Agent fabricates data instead of fetching it
Add tools to the task or agent

No guardrails on critical output
Bad output flows downstream unchecked
Add function or LLM guardrails

Overly strict expected_output
Agent loops trying to match impossible criteria
Be specific but achievable; lower guardrail_max_retries to fail faster

Description duplicates backstory
Wasted tokens and confused agent
Description = what to do; backstory = who you are

10. Task Design Checklist

Before running a task, verify:

 Description includes what, how, context, and constraints

 Expected output specifies format, structure, and quality markers

 Single purpose — one clear objective per task

 Agent assigned (or task is in a hierarchical crew)

 Dependencies set via context where needed

 Tools provided for any task requiring external data

 Structured output configured if downstream code parses the result

 Guardrails set for critical outputs

 Variables in YAML match the inputs dict keys

 Expected output is achievable — test with a simple run before adding complexity

References

For deeper dives into specific topics, see:

Structured Output — output_pydantic, output_json, and response_format patterns across LLM, Agent, Task, and Crew levels

For related skills:

getting-started — project scaffolding, choosing the right abstraction, Flow architecture

design-agent — agent Role-Goal-Backstory framework, parameter tuning, tool assignment, memory & knowledge configuration

ask-docs — query the live CrewAI documentation MCP server for questions not covered by these skills