> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compozy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

> Workflows in Compozy are defined using YAML configuration files. Each workflow consists of tasks and configuration that work together to automate your processes.

## Basic Structure

Tasks in workflows follow a consistent structure and can be defined in three ways:

<CodeGroup>
  ```yaml Inline Tasks theme={"dark"}
  workflow:
    tasks:
      - id: send_notification
        type: basic
        use: compozy/tools:notification@1.0.0
        with:
          message: "{{ tasks.process_data.output }}"
        on_success:
          next: cleanup
  ```

  ```yaml Root-level Tasks theme={"dark"}
  tasks:
    - id: data_processor
      type: basic
      use: compozy/tools:data-processor@1.0.0
      schema:
        input:
          type: object
          properties:
            format:
              type: string
              enum: [json, xml]
      with:
        format: json

  workflow:
    tasks:
      - id: process_data
        use: task(data_processor)
        with:
          data: "{{ trigger.data }}"
        on_success:
          next: send_notification
  ```

  ```yaml External Tasks theme={"dark"}
  workflow:
    tasks:
      - id: process_data
        import: ./tasks/data_processor.yaml
        with:
          data: "{{ trigger.data }}"
        on_error:
          next: handle_error
  ```
</CodeGroup>

## Key Elements

<CardGroup cols={2}>
  <Card title="Tasks" icon="diagram-project">
    The actual work to be performed - see [Task Types](/core/tasks/types)
  </Card>

  <Card title="Flow Control" icon="code-branch">
    How tasks connect and interact with each other
  </Card>
</CardGroup>

<Note>
  For configuration of triggers, environment variables, and other base structure elements, please refer to the [Base Structure documentation](/core/base-structure/overview).
</Note>

## Basic Workflow Patterns

### Sequential Processing

Create linear workflows where tasks execute one after another:

```yaml theme={"dark"}
workflow:
  tasks:
    - id: fetch_data
      type: basic
      use: compozy/tools:api-fetch@1.0.0
      schema:
        input:
          type: object
          properties:
            url: string
      with:
        url: "{{ env.API_URL }}"
      on_success:
        next: process_data

    - id: process_data
      type: basic
      use: compozy/tools:data-transform@1.0.0
      with:
        data: "{{ tasks.fetch_data.output }}"
      on_success:
        next: save_results
      retry:
        attempts: 3
        backoff: exponential
        interval: 1s
```

### Conditional Logic

Add decision points to your workflow using decision tasks:

```yaml theme={"dark"}
workflow:
  tasks:
    - id: check_data
      type: decision
      condition: "{{ tasks.validate_input.output.is_valid }}"
      routes:
        "true": process_valid
        "false": handle_invalid
      on_condition_match:
        next: log_decision

    - id: process_valid
      type: basic
      use: compozy/tools:data-processor@1.0.0
      on_error:
        next: handle_error

    - id: handle_invalid
      type: basic
      use: compozy/tools:error-handler@1.0.0
```

### Parallel Processing

Execute tasks concurrently using parallel tasks:

```yaml theme={"dark"}
workflow:
  tasks:
    - id: process_batch
      type: parallel
      config:
        max_concurrent: 3
        fail_fast: false
      execute:
        - use: compozy/tools:processor-1@1.0.0
          retry:
            attempts: 3
        - use: compozy/tools:processor-2@1.0.0
          retry:
            attempts: 2
      on_error:
        next: handle_batch_error
```

### Composability

Break down workflows into reusable components:

```yaml theme={"dark"}
# tasks/shared.yaml
tasks:
  - id: document_processor
    type: basic
    use: compozy/tools:doc-processor@1.0.0
    schema:
      input:
        type: object
        properties:
          format:
            type: string
            enum: [pdf, docx]
    with:
      format: pdf

# workflow.yaml
workflow:
  tasks:
    - id: process_document
      import: ./tasks/shared.yaml
      with:
        document: "{{ trigger.document }}"
      on_success:
        next: notify_complete
```

## Memory Integration

Workflows can reference memory systems defined in the base configuration:

```yaml theme={"dark"}
workflow:
  memory: chat_memory    # Reference to memory defined in base config
  tasks:
    - id: chat_task
      type: basic
      use: compozy/tools:chat-processor@1.0.0
      with:
        context: "{{ memory.chat_memory.current_thread }}"
        history: "{{ memory.chat_memory.last_messages }}"
        relevant: "{{ memory.chat_memory.semantic_search }}"
```

## Best Practices

<Steps>
  <Step title="Task Design">
    * Keep tasks focused and single-purpose
    * Use appropriate task types
    * Define clear input/output schemas
  </Step>

  <Step title="Error Handling">
    * Configure retry policies
    * Implement fallback mechanisms
    * Use error routing effectively
  </Step>

  <Step title="Performance">
    * Use parallel tasks when possible
    * Configure appropriate concurrency
    * Implement efficient batching
  </Step>

  <Step title="Maintainability">
    * Break down complex workflows
    * Use schema validation
    * Document task requirements
  </Step>
</Steps>

## References

<CardGroup cols={2}>
  <Card title="Task Types" icon="list-check" href="/core/tasks/types">
    Learn about different types of tasks
  </Card>

  <Card title="Composability" icon="puzzle-piece" href="/core/workflows/composability">
    Break down workflows into components
  </Card>

  <Card title="Error Handling" icon="shield" href="/core/tasks/error-handling">
    Implement error handling strategies
  </Card>

  <Card title="Base Structure" icon="box" href="/core/base-structure/overview">
    Learn about triggers, env vars, and base configuration
  </Card>
</CardGroup>