CrewAI task design and configuration. Use when creating, configuring, or debugging crewAI tasks — writing descriptions and expected_output, setting up task dependencies with context, configuring output formats (output_pydantic, output_json, output_file), using guardrails for validation, enabling human_input, async execution, markdown formatting, or debugging task execution issues.
Instrucciones de origen · Vista previa de solo lectura
name
design-task
description
CrewAI task design and configuration. Use when creating, configuring, or debugging crewAI tasks — writing descriptions and expected_output, setting up task dependencies with context, configuring output formats (output_pydantic, output_json, output_file), using guardrails for validation, enabling human_input, async execution, markdown formatting, or debugging task execution issues.
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.Identifythetop
{}
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 taskresearch_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:researcherwriting_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:writerediting_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
classResearchReport(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.
Automatically instructs the agent to format output with proper markdown headers, lists, emphasis, and code blocks.
Callbacks
deflog_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
defvalidate_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:researcheranalysis_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:analystcontext:-research_taskreport_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:writeroutput_file:output/report.md
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
defneeds_more_data(output) -> bool:
returnlen(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={...}):
