Composite Tasks

When to Use Composite Tasks

Perfect for multi-step processes like user onboarding, document processing pipelines, or any workflow where tasks must execute in a specific order. For independent operations that can run simultaneously, consider parallel processing instead.

Overview

Composite tasks are the sequential orchestration engine of Compozy workflows, enabling you to group related tasks into logical units that execute one after another. They transform complex multi-step processes into reusable, maintainable components while providing sophisticated control over execution strategies and comprehensive error handling.

Sequential Execution

Tasks execute one after another, with each task waiting for the previous to complete, ensuring proper dependency management

Strategy Control

Choose between fail_fast for critical processes or best_effort for resilient operations with configurable error handling

Data Flow Integration

Outputs from each task automatically become available to subsequent tasks through template expressions

Hierarchical Composition

Composite tasks can contain other composite tasks, enabling complex nested workflows with different strategies

Task Structure

Every composite task shares this fundamental structure:

id: task-name
type: composite
strategy: fail_fast # or best_effort
tasks:
  - id: first-task
    type: basic
    action: process_message
    with:
      data: "{{ .workflow.input.data }}"
  - id: second-task
    type: basic
    action: format_output
    with:
      processed_data: "{{ .tasks.first-task.output.result }}"
outputs:
  result: "{{ .tasks.second-task.output.result }}"
on_success:
  next: next-workflow-task
on_error:
  next: error-handler

Execution Strategies

Composite tasks support two distinct execution strategies that determine how failures are handled during sequential execution. Understanding these strategies is crucial for building robust workflows that match your business requirements.

The fail_fast strategy (default) provides strict error handling by stopping execution immediately when any task fails. This strategy is essential for workflows where the integrity of the entire process depends on every step succeeding.

id: financial-transaction
type: composite
strategy: fail_fast  # Critical for financial operations

tasks:
  - id: validate-account
    type: basic
    action: validate_account
    with:
      account_id: "{{ .workflow.input.account_id }}"
      amount: "{{ .workflow.input.amount }}"

  - id: check-balance
    type: basic
    action: check_account_balance
    with:
      account_id: "{{ .workflow.input.account_id }}"
      required_amount: "{{ .workflow.input.amount }}"

  - id: process-transaction
    type: basic
    action: process_financial_transaction
    with:
      account_id: "{{ .workflow.input.account_id }}"
      amount: "{{ .workflow.input.amount }}"
      validation_result: "{{ .tasks.validate-account.output.result }}"

# If any task fails, the entire composite fails immediately
# No subsequent tasks will execute

Critical Process Integrity
Use when all tasks must succeed for the process to be valid - perfect for financial transactions, legal workflows, or security-sensitive operations
Dependency Chain Requirements
Ideal when failure of any step makes subsequent steps meaningless or dangerous to execute
System Consistency
Essential for maintaining data consistency and system integrity where partial completion could cause corruption
Compliance and Audit
Required for workflows that need complete audit trails and cannot have partial execution states

Fail Fast Best Practices: Always implement proper error handling and consider rollback strategies when using fail_fast for critical operations. Learn more about advanced patterns and workflow configuration for transient failures.

Hierarchical Organization

One of the most powerful features of composite tasks is their ability to contain other composite tasks, creating hierarchical workflow structures. This enables you to build complex, multi-layered processes while maintaining clear organization and different error handling strategies at each level.

Loading diagram...

Strategy Inheritance and Override

Hierarchical composite tasks allow you to apply different strategies at different levels:

id: complete-document-pipeline
type: composite
strategy: fail_fast

tasks:
  - id: document-processing
    type: composite
    strategy: best_effort  # Some processing steps can fail
    tasks:
      - id: extract-text
        type: basic
        action: extract_document_text
        with:
          document: "{{ .workflow.input.document }}"

      - id: extract-images
        type: basic
        action: extract_document_images
        with:
          document: "{{ .workflow.input.document }}"

      - id: extract-metadata
        type: basic
        action: extract_document_metadata
        with:
          document: "{{ .workflow.input.document }}"

  - id: content-analysis
    type: composite
    strategy: fail_fast  # Analysis must be complete
    tasks:
      - id: analyze-text
        type: basic
        action: analyze_text_content
        with:
          text: "{{ .tasks.document-processing.tasks.extract-text.output.content }}"

      - id: analyze-structure
        type: basic
        action: analyze_document_structure
        with:
          text: "{{ .tasks.document-processing.tasks.extract-text.output.content }}"
          metadata: "{{ .tasks.document-processing.tasks.extract-metadata.output.metadata }}"

  - id: generate-outputs
    type: composite
    strategy: best_effort  # Some outputs are optional
    tasks:
      - id: create-summary
        type: basic
        action: create_document_summary
        with:
          text_analysis: "{{ .tasks.content-analysis.tasks.analyze-text.output.analysis }}"
          structure_analysis: "{{ .tasks.content-analysis.tasks.analyze-structure.output.structure }}"

      - id: create-keywords
        type: basic
        action: extract_keywords
        with:
          text_analysis: "{{ .tasks.content-analysis.tasks.analyze-text.output.analysis }}"

      - id: create-report
        type: basic
        action: generate_final_report
        with:
          summary: "{{ .tasks.create-summary.output.summary }}"
          keywords: "{{ .tasks.create-keywords.output.keywords }}"
          raw_data: "{{ .tasks.document-processing.outputs }}"

outputs:
  processing_results: "{{ .tasks.document-processing.outputs }}"
  analysis_results: "{{ .tasks.content-analysis.outputs }}"
  final_outputs: "{{ .tasks.generate-outputs.outputs }}"

  # High-level summary
  document_summary: "{{ .tasks.generate-outputs.tasks.create-summary.output.summary }}"
  keywords: "{{ .tasks.generate-outputs.tasks.create-keywords.output.keywords }}"
  full_report: "{{ .tasks.generate-outputs.tasks.create-report.output.report }}"

Best Practices

Successful composite task implementation requires careful consideration of strategy selection, data flow design, and error handling patterns. These practices ensure your workflows are maintainable, reliable, and performant.

Composite Task Mastery: Once you've mastered basic composite patterns, explore collection tasks for array processing and router tasks for dynamic branching. These task types complement composite tasks to create sophisticated workflow architectures.

Next Steps

Composite tasks are central to Compozy's workflow orchestration capabilities. Understanding how they integrate with other task types and system components will help you build sophisticated, production-ready workflows.

Essential Foundation Knowledge:

Basic Tasks

Master the fundamental building blocks that form the foundation of all composite task workflows

Agent Integration

Learn how AI agents work within composite workflows for intelligent task execution

Tool Development

Understand how to build and integrate custom tools for specialized composite task operations

YAML Templates

Master the template system that powers dynamic data flow between composite task steps