Workflow YAML Definition

Overview

A Stavily workflow is defined using a structured YAML file that describes the complete automation process, from triggers to actions and outputs. The schema supports hierarchical agent definitions, conditional execution, error handling, and monitoring.

Workflow Structure

graph TD
    A[Workflow Metadata] --> B[Agents]
    B --> C[Triggers]
    C --> D[Actions]
    D --> E[Outputs]
    E --> F[Monitoring]

Key Concepts

Hierarchical Agent Assignment: Agents can be defined at workflow, type, or step level
Dependency Management: Steps can depend on others with conditional execution
Error Handling: Built-in retry logic and failure strategies
Plugin Architecture: Versioned plugins for triggers, actions, and outputs

Complete Example

Below is a comprehensive example of a workflow.yaml file demonstrating all current features.

name: "High CPU Remediation with Escalation"
description: "Multi-step remediation for high CPU usage"
version: "1.2.0"

# Workflow-wise agent definition
agents:
  pools:
      - pool_name: "production-servers"
        agent_regex: "prod-.*"
        auto_install_plugins: true
        on_plugin_missing: "skip_agent"
      - pool_name: "staging-servers"
        agent_regex: "staging-.*"
  single_agent: "specific-agent-01"

triggers:
  # Type-wise agent definition for triggers
  agents:
    single_agent: "trigger-specific-agent-01"
  steps:
    - name: "cpu-threshold"
      plugin: "prometheus-trigger-v1.0.0"
      config:
        metric: "cpu_usage_percent"
        condition: "> 90"
        duration: "2m"

actions:
  # Type-wise agent definition for actions
  agents:
    pools:
        - pool_name: "actions-pool"
          agent_regex: "actions-.*"
  steps:
    - name: "analyze-processes"
      plugin: "python-script-action-v2.1.0"
      # Plugin-wise agent definition
      agents:
        pools:
            - pool_name: "analysis-pool"
              agent_regex: "analysis-.*"
      depends_on: []
      config:
        script: "analyze_cpu_processes.py"
        timeout: "30s"
      error_handling:
        on_failure: "continue"
        max_retries: 3
        retry_delay: "30s"

    - name: "kill-high-cpu-processes"
      plugin: "system-command-action-v1.0.0"
      agents:
        single_agent: "killer-agent-007"
      depends_on: ["analyze-processes"]
      condition: "analyze-processes.output.high_cpu_count > 3"
      config:
        command: "pkill -f high_cpu_process"
        timeout: "10s"

    - name: "restart-service"
      plugin: "service-management-action-v1.5.0"
      depends_on: ["kill-high-cpu-processes"]
      condition: "kill-high-cpu-processes.status == 'failed'"
      config:
        service: "webapp"
        action: "restart"

outputs:
  # Type-wise agent definition for outputs
  agents:
    single_agent: "output-agent-01"
  steps:
    - name: "send-alert"
      plugin: "formatted-email-output-v1.5.0"
      depends_on: ["analyze-processes"]
      config:
        recipients: ["[email protected]"]
        template: "cpu_remediation_report"

monitoring:
  timeout: "10m"
  heartbeat_interval: "30s"
  progress_tracking: true

Schema Breakdown

The workflow schema is organized into logical sections. Each section serves a specific purpose in the workflow lifecycle.

The root-level properties provide essential metadata and identification for your workflow.

Core Metadata Fields

name: Human-readable name displayed in the UI
description: Brief explanation of the workflow’s purpose
version: Semantic version number (e.g., “1.2.0”)
created_by: Author or team responsible for the workflow
tags: Array of strings for categorization and filtering

# Basic workflow identification
name: "High CPU Remediation with Escalation"
description: "Multi-step remediation for high CPU usage with monitoring and escalation"
version: "1.2.0"
created_by: "devops-team"
tags: ["remediation", "cpu", "monitoring", "production"]

Optional Metadata

# Extended metadata for organization and UI
metadata:
revision: 3
environment: "production"
category: "infrastructure"
ui:
  color: "#4B9EFF"
  icon: "cpu"

Agents define where and how your workflow components execute. Stavily supports hierarchical agent assignment for maximum flexibility.

Agent Hierarchy

graph TD
    A[Workflow Level] --> B[Type Level]
    B --> C[Step Level]

    A --> D[All components]
    B --> E[All steps in block]
    C --> F[Single step only]

1. Workflow Level

Top-level definition applies to all triggers, actions, and outputs unless overridden.

2. Type Level

Defined within triggers, actions, or outputs blocks - overrides workflow level for that component type.

3. Step Level

Most specific - defined within individual steps for precise agent targeting.

Agent Configuration

Pool Configuration

pool_name: Descriptive name for the agent pool
agent_regex: Regular expression to match agent names (e.g., “prod-.*”)
auto_install_plugins: Automatically install required plugins on agents
on_plugin_missing: Behavior when plugins are missing (“skip_agent” or “fail_workflow”)

Single Agent

single_agent: Direct agent ID for targeted execution

# Example: Multi-level agent configuration
agents:
pools:
  - pool_name: "production-servers"
    agent_regex: "prod-.*"
    auto_install_plugins: true
    on_plugin_missing: "skip_agent"
single_agent: "fallback-agent-01"

Triggers define the events that initiate workflow execution. They monitor external systems and fire when conditions are met.

Trigger Lifecycle

stateDiagram-v2
    [*] --> Listening
    Listening --> Condition_Met: Event occurs
    Condition_Met --> Workflow_Started: Validation passed
    Workflow_Started --> [*]
    Listening --> Timeout: No activity
    Timeout --> [*]

Trigger Components

agents: Type-level agent assignment for all triggers
steps: Array of trigger definitions, each monitoring a specific event

Trigger Step Fields

name: Unique identifier for the trigger step
plugin: Versioned trigger plugin (e.g., “prometheus-trigger-v1.0.0”)
config: Plugin-specific configuration parameters
enabled: Boolean to enable/disable the trigger (default: true)

triggers:
agents:
  single_agent: "monitoring-agent-01"
steps:
  - name: "cpu-threshold-alert"
    plugin: "prometheus-trigger-v1.1.0"
    config:
      metric: "cpu_usage_percent"
      condition: "> {{ variables.cpu_threshold }}"
      duration: "2m"
      labels:
        severity: "high"
  - name: "manual-override"
    plugin: "manual-trigger-v1.0.0"
    enabled: false
    config:
      description: "Manual trigger for testing"

Actions are the core execution steps of your workflow. They perform tasks, process data, and implement your automation logic.

Action Execution Flow

graph TD
    A[Action Triggered] --> B{Check Dependencies}
    B -->|Dependencies Met| C{Evaluate Condition}
    C -->|Condition True| D[Execute Action]
    D --> E{Result}
    E -->|Success| F[Continue Workflow]
    E -->|Failure| G[Error Handling]

    B -->|Dependencies Failed| H[Skip Action]
    C -->|Condition False| H
    G --> I[Retry/Compensation]

Action Components

agents: Type-level agent assignment for all actions
steps: Array of action definitions with execution logic

Action Step Fields

name: Unique identifier for the action step
plugin: Versioned action plugin (e.g., “python-script-action-v2.1.0”)
agents: Step-level agent override (optional)
depends_on: Array of step names that must complete first
condition: Expression that must evaluate to true for execution
config: Plugin-specific parameters and settings
error_handling: Failure recovery and retry configuration
timeout: Maximum execution time for the step

actions:
agents:
  pools:
    - pool_name: "execution-pool"
      agent_regex: "exec-.*"
steps:
  - name: "analyze-processes"
    plugin: "python-script-action-v2.1.0"
    depends_on: []
    config:
      script: "analyze_cpu_processes.py"
      timeout: "30s"
    error_handling:
      on_failure: "continue"
      max_retries: 3
      retry_delay: "15s"

  - name: "kill-high-cpu-processes"
    plugin: "system-command-action-v1.2.0"
    depends_on: ["analyze-processes"]
    condition: "analyze-processes.output.high_cpu_count > 3"
    config:
      command: "pkill -f high_cpu_process"
      timeout: "10s"
    error_handling:
      on_failure: "invoke-compensation"

Outputs define how workflow results are communicated and stored. They handle notifications, reports, and data persistence.

Output Processing

graph TD
    A[Workflow Complete] --> B{Results Available}
    B -->|Success| C[Format Output]
    B -->|Partial| D[Format Partial Results]
    B -->|Failure| E[Send Error Notification]

    C --> F[Execute Output Steps]
    D --> F
    E --> F

    F --> G[Deliver Results]
    G --> H[Archive/Log Data]

Output Components

agents: Type-level agent assignment for all outputs
steps: Array of output definitions for result handling

Output Step Fields

name: Unique identifier for the output step
plugin: Versioned output plugin (e.g., “email-output-v1.5.0”)
depends_on: Array of steps that must complete before output
condition: Optional condition for conditional output
config: Plugin-specific configuration (recipients, templates, etc.)
attachments: Files or data to include with output

outputs:
agents:
  single_agent: "notification-agent-01"
steps:
  - name: "send-remediation-report"
    plugin: "formatted-email-output-v1.5.0"
    depends_on: ["restart-service"]
    config:
      recipients: ["[email protected]", "[email protected]"]
      template: "cpu_remediation_summary"
      subject: "CPU Remediation Complete - {{ workflow.name }}"
      attachments:
        - path: "logs/workflow-{{ workflow.id }}.txt"
        - path: "metrics/cpu_metrics.json"

  - name: "archive-results"
    plugin: "s3-storage-output-v1.0.0"
    depends_on: ["send-remediation-report"]
    config:
      bucket: "stavily-workflow-results"
      key: "remediations/{{ workflow.id }}/{{ timestamp }}"
      data: "{{ workflow.outputs }}"

Monitoring settings control workflow observability, timeouts, and health tracking throughout execution.

Monitoring Architecture

graph TD
    A[Workflow Start] --> B[Initialize Monitoring]
    B --> C[Start Heartbeat Timer]
    B --> D[Set Global Timeout]
    B --> E[Enable Progress Tracking]

    C --> F[Send Heartbeat]
    F --> G{Workflow Active?}
    G -->|Yes| F
    G -->|No| H[Stop Monitoring]

    D --> I[Check Timeout]
    I --> J{Exceeded?}
    J -->|No| I
    J -->|Yes| K[Trigger Timeout Action]

    E --> L[Track Step Progress]
    L --> M[Update Status]
    M --> L

Monitoring Fields

timeout: Maximum total execution time (e.g., “15m”, “1h”)
heartbeat_interval: Frequency of status updates to orchestrator
progress_tracking: Enable detailed step-by-step progress reporting
log_level: Logging verbosity (“debug”, “info”, “warn”, “error”)
metrics: Prometheus metrics export configuration

monitoring:
timeout: "15m"
heartbeat_interval: "30s"
progress_tracking: true
log_level: "debug"
metrics:
  enabled: true
  export_to: "prometheus"
  labels:
    workflow_type: "remediation"
    environment: "production"