What is ConditionalTask?
ConditionalTask wraps the same execution contract as Task but inserts a gate evaluated against CrewState before the scheduler commits the step. Typical uses are skipping translation when the detected language is already English, skipping enrichment when upstream JSON already contains a confidence score, or omitting expensive vision analysis when an image hash matches a known-good cache entry. The callable should be pure, fast, and deterministic given the same state snapshot — heavy work belongs in a prior task that writes results into state, not inside the condition itself.
Compared with Flows and @router, ConditionalTask keeps branching inside the Crew abstraction with a single boolean predicate rather than explicit graph edges. That reduces boilerplate for one-off skips but does not replace arbitrary DAGs: when you need multiple labeled branches, retries with different paths, or human approvals mid-branch, migrate the logic to Flow. CrewAI evaluates the condition at scheduling time; if your predicate reads mutable global state instead of CrewState, you will get flaky runs that are painful to replay or test.
When to Use
Optional steps inside an otherwise linear Crew where a single yes/no gate on shared state is enough.
Use Cases
- • Skip-translation pattern
- • Optional enrichment
- • Branching prep before a fixed pipeline
Key Features
- ✓ Runtime condition on CrewState
- ✓ Drop-in Task shape
- ✓ Keeps branching inside Crew
When NOT to Use
Rich branching, human-in-the-loop approvals, or multi-way routers — model those in Flow instead.
Notes
Strict booleans
Return True or False explicitly. Truthy numbers or non-empty strings are easy to write by accident and make conditions harder to reason about during code review.
State shape discipline
The predicate only sees what earlier tasks wrote into CrewState. Document which keys you rely on and fail closed when keys are missing — silent getattr defaults can hide upstream bugs.
Testing
Unit-test the callable with frozen state dicts or fixtures. Integration tests should cover both branches so CI proves the skipped path does not regress when descriptions change.
Interaction with async tasks
When neighboring tasks use async_execution=True, ordering and state visibility still follow Crew rules. Do not assume the condition runs after all async siblings complete unless your context wiring guarantees it.
Import
from crewai.tasks.conditional_task import ConditionalTaskKey Parameters
| Parameter | Type | Default | Purpose |
|---|---|---|---|
| condition | Callable[[CrewState], bool] | — | Predicate evaluated at scheduling time. |
Code Examples
Skip translation when language is English
from crewai.tasks.conditional_task import ConditionalTask
ConditionalTask(
condition=lambda s: getattr(s, 'detected_lang', None) != 'en',
description='Translate the summary to English',
agent=translator,
)Run audit task only when risk score crosses a threshold
ConditionalTask(
condition=lambda s: float(getattr(s, 'risk_score', 0)) >= 0.7,
description='Perform compliance audit on the draft',
agent=auditor,
)Combine with ordinary Task ordering
from crewai import Task
from crewai.tasks.conditional_task import ConditionalTask
detect = Task(description='Detect language', agent=analyst)
translate = ConditionalTask(
condition=lambda s: s.detected_lang != 'en',
description='Translate',
agent=translator,
context=[detect],
)
finalize = Task(description='Publish', agent=publisher, context=[detect, translate])Common Mistakes
❌ Returning truthy non-bool
✅ Return strict True/False.
❌ Encoding business logic that needs three or more branches
✅ Switch to Flow with @router tags for clearer control flow.
ConditionalTask FAQ
What is ConditionalTask in CrewAI?
A Task that executes only if a runtime condition (callable returning bool) is True. ConditionalTask wraps the same execution contract as Task but inserts a gate evaluated against CrewState before the scheduler commits the step. Typical uses are skipping translation when the detected language is already English, skipping enrichment when upstream JSON already contains a confidence score, or omitting expensive vision analysis when an image hash matches a known-good cache entry. The callable should be pure, fast, and deterministic given the same state snapshot —…
Which package defines the CrewAI class ConditionalTask?
DevShelfHub maps ConditionalTask to Python module crewai.tasks.conditional_task (package path crewai.tasks.conditional_task in this reference). Pin your installed crewai version and match imports to the snippet on this page.
When should I use ConditionalTask?
Optional steps inside an otherwise linear Crew where a single yes/no gate on shared state is enough.
When should I avoid using ConditionalTask?
Rich branching, human-in-the-loop approvals, or multi-way routers — model those in Flow instead.
How do I import ConditionalTask in Python?
from crewai.tasks.conditional_task import ConditionalTask
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.