​
Common Structure

All task types in Compozy share a common base structure with the following fields: 
- id: string           # Unique identifier for the task
  name: string         # Optional human-readable name
  type: string         # Task type identifier
  import: string       # Path to external task definition
  schema:             # Optional schema definition
    input: object     # Input schema for task parameters
  env: object         # Task-specific environment variables
  config: object      # Optional configuration
  retry:             # Retry configuration
    attempts: number
    backoff: string
    interval: duration
    max_interval: duration
    jitter: boolean
  on_start: object    # Task start handler
  on_success: object  # Success handler
  on_error: object    # Error handler
  on_complete: object # Completion handler
Each task type extends this common structure with its specific fields and configurations. Tasks provide access to state information through event handlers: 
status: string        # Current task status (running, success, error)
duration: number      # Task duration in milliseconds
start_time: string    # Task start timestamp
end_time: string      # Task end timestamp
retry_count: number   # Number of retry attempts made
error: object        # Error information if failed
output: any          # Task output data

​
Basic

This is the default if you don’t specify a type.
# Extends common structure with:
use: string|object   # Tool or agent reference
with: object        # Input parameters
Best Used For:
  • Single operations
  • API calls
  • Data transformations
  • Simple processing steps
JSON Schema
https://compozy.dev/schemas/task-basic.json
{
  "type": "object",
  "required": ["id", "type", "use"],
  "properties": {
    "id": { "type": "string" },
    "type": { "const": "basic" },
    "use": {
      "oneOf": [
        { "type": "string" },
        {
          "type": "object",
          "required": ["repo", "package"],
          "properties": {
            "repo": { "type": "string" },
            "package": { "type": "string" },
            "version": { "type": "string" }
          }
        }
      ]
    },
    "with": { "type": "object" }
  }
}

​
Parallel

Executes multiple operations simultaneously to improve performance 
# Extends common structure with:
config:             # Parallel-specific configuration
  max_concurrent: number
  fail_fast: boolean
  timeout: duration
execute:            # List of operations
  - use: string     # Tool/agent reference
    with: object    # Operation parameters
    retry: object   # Operation-specific retry
    on_error: object # Operation error handler
Best Used For:
  • Independent operations
  • Performance optimization
  • Batch processing
  • Multiple API calls
JSON Schema
https://compozy.dev/schemas/task-parallel.json
{
  "type": "object",
  "required": ["id", "type", "execute"],
  "properties": {
    "id": { "type": "string" },
    "type": { "const": "parallel" },
    "config": {
      "type": "object",
      "properties": {
        "max_concurrent": { "type": "number" },
        "fail_fast": { "type": "boolean" },
        "timeout": { "type": "string" }
      }
    },
    "execute": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["use"],
        "properties": {
          "use": { "type": "string" },
          "with": { "type": "object" },
          "retry": { "type": "object" },
          "on_error": { "type": "object" }
        }
      }
    }
  }
}

​
Decision

Routes execution based on conditions or data values. 
# Extends common structure with:
condition: string    # Single condition
conditions: array   # Multiple conditions
routes: object      # Route mapping
default: object     # Default route
Best Used For:
  • Business logic implementation
  • Content-based routing
  • Error handling flows
  • Multi-path processing
JSON Schema
https://compozy.dev/schemas/task-decision.json
{
  "type": "object",
  "required": ["id", "type"],
  "properties": {
    "id": { "type": "string" },
    "type": { "const": "decision" },
    "condition": { "type": "string" },
    "conditions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["condition", "next"],
        "properties": {
          "condition": { "type": "string" },
          "next": { "type": "string" }
        }
      }
    },
    "routes": { "type": "object" },
    "default": {
      "type": "object",
      "properties": {
        "next": { "type": "string" }
      }
    }
  }
}

​
Collection

Processes arrays of items efficiently, with support for batching and parallel execution. 
# Extends common structure with:
input: array        # Input array
config:             # Collection-specific config
  mode: string      # parallel/sequential
  batch_size: number
  max_concurrent: number
  continue_on_error: boolean
  timeout_per_batch: duration
  timeout_per_item: duration
execute:            # Item operation
  - use: string     # Tool/agent reference
    with: object    # Operation parameters
on_item_start: object    # Item start handler
on_item_success: object  # Item success handler
on_item_error: object    # Item error handler
on_batch_start: object   # Batch start handler
on_batch_complete: object # Batch completion handler
Best Used For:
  • Processing arrays of items
  • Batch processing
  • Parallel data processing
  • Rate-limited operations
JSON Schema
https://compozy.dev/schemas/task-collection.json
{
  "type": "object",
  "required": ["id", "type", "input", "execute"],
  "properties": {
    "id": { "type": "string" },
    "type": { "const": "collection" },
    "input": { "type": "array" },
    "config": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": ["parallel", "sequential"]
        },
        "batch_size": { "type": "number" },
        "max_concurrent": { "type": "number" },
        "continue_on_error": { "type": "boolean" },
        "timeout_per_batch": { "type": "string" },
        "timeout_per_item": { "type": "string" }
      }
    },
    "execute": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["use"],
        "properties": {
          "use": { "type": "string" },
          "with": { "type": "object" }
        }
      }
    }
  }
}

​
Wait

Pauses execution until specific conditions are met or a timeout occurs. 
# Extends common structure with:
config:             # Wait-specific configuration
  timeout: duration
  check_interval: duration
  max_checks: number
condition: string    # Wait condition
on_timeout: object  # Timeout handler
on_check: object    # Condition check handler
Best Used For:
  • Human approval flows
  • External service integration
  • Time-based operations
  • Rate limiting
JSON Schema
https://compozy.dev/schemas/task-wait.json
{
  "type": "object",
  "required": ["id", "type", "config", "condition"],
  "properties": {
    "id": { "type": "string" },
    "type": { "const": "wait" },
    "config": {
      "type": "object",
      "required": ["timeout", "check_interval"],
      "properties": {
        "timeout": { "type": "string" },
        "check_interval": { "type": "string" },
        "max_checks": { "type": "number" }
      }
    },
    "condition": { "type": "string" }
  }
}

​
Map

Transforms data between tasks while maintaining type safety. 
# Extends common structure with:
config:             # Map-specific configuration
  validate_schema: boolean
  strict_mode: boolean
input: object       # Input data
mapping: object     # Output mapping
on_validation_error: object # Schema validation error handler
Best Used For:
  • Data transformation
  • Schema validation
  • Field mapping
  • Response formatting
JSON Schema
https://compozy.dev/schemas/task-map.json
{
  "type": "object",
  "required": ["id", "type", "input", "mapping"],
  "properties": {
    "id": { "type": "string" },
    "type": { "const": "map" },
    "config": {
      "type": "object",
      "properties": {
        "validate_schema": { "type": "boolean" },
        "strict_mode": { "type": "boolean" }
      }
    },
    "input": { "type": "object" },
    "mapping": { "type": "object" }
  }
}

​
Composite

Groups multiple operations into a single, reusable unit. 
# Extends common structure with:
config:             # Composite-specific configuration
  error_handling: string  # continue/stop
  timeout: duration
tasks:              # Subtasks list
  - id: string      # Subtask identifier
    type: string    # Subtask type
    ...            # Subtask configuration
on_task_start: object    # Subtask start handler
on_task_complete: object # Subtask completion handler
Best Used For:
  • Reusable task sequences
  • Complex workflows
  • Modular task design
  • Process encapsulation
JSON Schema
https://compozy.dev/schemas/task-composite.json
{
  "type": "object",
  "required": ["id", "type", "tasks"],
  "properties": {
    "id": { "type": "string" },
    "type": { "const": "composite" },
    "config": {
      "type": "object",
      "properties": {
        "error_handling": {
          "type": "string",
          "enum": ["continue", "stop"]
        },
        "timeout": { "type": "string" }
      }
    },
    "tasks": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "type"],
        "properties": {
          "id": { "type": "string" },
          "type": { "type": "string" }
        }
      }
    }
  }
}

​
Best Practices

Choose the Right Type

Select task types based on your specific needs:
  • Use Basic for simple operations
  • Use Parallel for independent concurrent operations
  • Use Decision for conditional flows
  • Use Collection/Foreach for iterative processing
  • Use Wait for external dependencies
  • Use Map for data transformations
  • Use Composite for reusable workflows

Event Handling

Implement appropriate event handlers:
  • Use on_start for initialization
  • Use on_success/on_error for outcomes
  • Use on_complete for cleanup
  • Implement type-specific handlers
  • Log important state changes

Error Management

Implement proper error handling:
  • Configure retry policies
  • Use conditional error routing
  • Handle partial failures
  • Implement fallback mechanisms
  • Log error details

State Management

Monitor and manage task state:
  • Track execution progress
  • Monitor performance metrics
  • Log state transitions
  • Handle state persistence
  • Implement recovery mechanisms

​
Next Steps

Types

Learn about different task types and their use cases

Usage

Understand how to use tasks in your workflows

API reference

Review the task configuration API reference

Registry

Learn about publishing tasks to the registry