​
Structure

Tasks in Compozy follow a consistent structure that supports both simple operations and complex flow control. For detailed information about task types and their specific structures, see the Task Types documentation.

tasks:
  - id: string           # Unique identifier for the task
    name: string         # Optional human-readable name
    type: string         # Task type (basic, parallel, collection, etc.)
    use: string|object   # Task implementation reference
    import: string       # Path to external task definition
    config: object       # Task type-specific configuration
    memory: string       # Memory store identifier
    schema:             # Optional schema definition
      input: object     # Input schema for task parameters
    with: object        # Task-specific configuration
    env: object         # Task-specific environment variables
    on_start: object    # Task start handler
    on_success: object  # Success handler
    on_error: object    # Error handler
    on_complete: object # Completion handler (runs after success/error)
    retry:             # Retry configuration
      attempts: number
      backoff: string
      interval: duration

​
Task Types

Basic

Simple, single-operation tasks for API calls, transformations, and processing steps.

Parallel

Execute multiple operations simultaneously with configurable concurrency limits.

Decision

Route execution based on conditions with support for complex business logic.

Collection

Process arrays of items sequentially or in parallel with advanced execution patterns.

Wait

Pause execution until specific conditions are met or timeout occurs.

Map

Transform data between tasks with type-safe field mapping.

Composite

Group multiple operations into reusable units.

​
Event Handlers

Tasks support various event handlers to control flow and handle state transitions:

tasks:
  - id: process_document
    type: basic
    use: tool(document-processor)
    on_start:
      next: log_start
      with:
        task: "{{ id }}"
        timestamp: "{{ now() }}"
    on_success:
      next: handle_success
      with:
        result: "{{ output }}"
    on_error:
      next: handle_error
      with:
        error: "{{ error }}"
    on_complete:
      next: cleanup
      with:
        status: "{{ status }}"
        duration: "{{ duration }}"

​
Error Handling & Recovery

Tasks support sophisticated error handling and recovery mechanisms:

tasks:
  - id: api_call
    type: basic
    use: tool(api-client)
    retry:
      attempts: 3
      backoff: exponential
      interval: 1s
    on_error:
      next: handle_failure
      with:
        attempts: "{{ retry_count }}"
        error: "{{ error }}"

​
Schema Definition

Schemas in Compozy use JSON Schema format to validate task inputs. Note that outputs are handled by the executed components (agents, MCPs, or tools):

tasks:
  - id: analyze_content
    type: basic
    use: tool(content-analyzer)
    schema:
      input:
        type: object
        properties:
          language:
            type: string
            enum: [en, es, fr]
            default: en
    with:
      model: basic
      language: "{{ input.language }}"

​
Environment Variables

Configure task-specific settings and secrets:

tasks:
  - id: api_call
    type: basic
    use: tool(api-client)
    env:
      API_KEY: "{{ env.SERVICE_KEY }}"
      TIMEOUT: "30"
    with:
      endpoint: /data

​
Task Imports

Reuse and customize tasks from external files:

tasks:
  - id: custom_processor
    import: ./tasks/content-processor.yaml
    env:
      OPTIMIZATION_LEVEL: low
    with:
      platform: blog

​
State Management

Tasks maintain state information that can be accessed in event handlers:

tasks:
  - id: process_data
    type: basic
    use: tool(data-processor)
    on_complete:
      next: log_metrics
      with:
        task_id: "{{ id }}"
        status: {{ status }}        # success, error, timeout
        duration: {{ duration }}    # Task duration in ms
        start_time: "{{ start_time }}"
        end_time: "{{ end_time }}"
        retries: "{{ retry_count }}"
        error: {{ error }}          # Error object if failed

​
Memory Integration

Tasks can interact with workflow-level memory systems for state persistence and context management. First, define memory at the workflow level, then reference it in tasks:

# Define memory in workflow
memory:
  chat_memory:
    id: chat_memory
    storage:
      use: compozy/storage:postgres
    vector:
      use: compozy/vector:pinecone
      dimensions: 1536
    options:
      lastMessages: 10
      semanticRecall:
        enabled: true

# Use memory in tasks
tasks:
  - id: chat_task
    type: basic
    use: tool(chat-processor)
    memory: chat_memory    # Reference to workflow memory
    with:
      context: "{{ memory.chat_task.current_thread }}"
      history: "{{ memory.chat_task.last_messages }}"
      relevant: "{{ memory.chat_task.semantic_search }}"

Memory operations in tasks support:

  • Reading from and writing to memory stores
  • Semantic search across stored content
  • Thread and conversation management
  • Context windowing and retrieval
  • Vector similarity search
  • Memory persistence and cleanup

​
Best Practices

1

Task Design

  • Choose appropriate task types for your needs
  • Keep tasks focused and single-purpose
  • Use parallel tasks judiciously
2

Configuration

  • Set reasonable defaults for concurrent operations
  • Use environment variables for sensitive data
  • Document task requirements
3

Event Handling

  • Implement appropriate handlers for critical events
  • Use on_complete for cleanup operations
  • Log important state transitions
4

Error Management

  • Configure retries for transient failures
  • Use conditional error routing
  • Implement graceful degradation
5

State Management

  • Monitor task state changes
  • Implement appropriate logging
  • Use state information for debugging
6

Recovery Strategies

  • Configure appropriate retry policies
  • Implement fallback mechanisms
  • Handle partial failures in parallel tasks

​
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