TaskGroup
The TaskGroup class is a container for organizing and executing multiple tasks or nested task groups as a single unit.
Overview
TaskGroup provides a way to:
- Group related tasks together for logical organization
- Execute multiple tasks in sequence
- Nest task groups within other task groups
- Manage complex task hierarchies
Unlike individual tasks, TaskGroups don’t transform data themselves—they simply orchestrate the execution of their contained tasks.
Class Diagram
Execution Flow
Constructor Parameters
| Parameter | Type | Description |
|---|---|---|
name | Optional[str] | Name for the task group (defaults to auto-generated UUID) |
tasks | List[Union[Task, TaskGroup]] | List of tasks or nested task groups to execute |
TaskGroup vs Task with Subtasks
There are two ways to compose tasks together:
Using TaskGroup
- Loose coupling: Tasks are independent
- No shared state: Each task manages its own inputs/outputs
- Flexible: Can mix different task types freely
- Simple execution: Just runs tasks in order
Using Task with Subtasks
- Tight coupling: Subtasks share parent’s inputs/outputs
- Shared models: Parent ensures subtasks have required models
- Validated dependencies: Parent checks model requirements
- Orchestrated: Parent controls subtask execution
Visualization Example
Best Practices
- Use meaningful names: Help identify the purpose of each group in logs
- Keep groups focused: Group related tasks together logically
- Avoid deep nesting: Too many levels make debugging difficult
- Consider alternatives: Use Task with subtasks when tasks need to share data
- Document structure: Add comments explaining the grouping strategy
When to Use TaskGroup
✅ Use TaskGroup when:
- You need to organize independent tasks
- Tasks don’t share data models
- You want simple sequential execution
- You’re building flexible, dynamic pipelines
❌ Don’t use TaskGroup when:
- Tasks need to pass data between them
- You need to validate model dependencies
- You want parent control over subtask execution
- Tasks should share the same inputs/outputs
In those cases, use a Task with subtasks instead.
Related
- Task - The base task class
- ProcessingTask - Example of task composition with subtasks
- ReportsTask - Another orchestrator task example
Last updated on