Workflow

Overview

Workflows are the core building blocks of Compozy that orchestrate the execution of AI agents, tools, and tasks. They provide a declarative way to define complex AI-powered applications through YAML configuration. Each workflow can include input validation, environment configuration, event triggers, automated scheduling, and output transformation.

If you're new to Compozy workflows, start with the Quick Start Guide for a 5-minute introduction, or dive deeper with the First Workflow Tutorial to build a complete AI-powered application.

This page covers workflow configuration in detail. For workflow execution, see the Workflow Commands or Workflow API.

Basic Structure

Every workflow starts with essential metadata that identifies and describes its purpose. Workflows are typically stored in your project directory as workflow.yaml files or in a workflows/ folder for multiple workflows.

id: my-workflow
version: "1.0.0"
description: "Workflow purpose and description"
author:
  name: "Your Name"
  email: "your.email@example.com"

The workflow ID must be unique within your project and is used when executing workflows via CLI or API. Version tracking helps manage workflow evolution over time.

Configuration Options

Workflow configuration controls how your workflow behaves at runtime. These settings define input validation rules, environment variables, and other execution parameters. All configuration options are defined under the config key in your workflow YAML.

Input Validation

Compozy uses JSON Schema to validate workflow inputs, ensuring data integrity before execution begins. This prevents errors and provides clear feedback when inputs don't match expected formats.

config:
  input:
    type: object
    properties:
      message:
        type: string
        minLength: 10
      priority:
        type: string
        enum: [low, medium, high]
    required: [message]

For reusable validation, reference schemas using Compozy's $ref directive:

config:
  input:
    $ref: "local::schemas.#(id==\"user_input\")"

Input validation errors are returned when executing workflows, helping developers quickly identify and fix issues.

Environment Variables

Configure runtime environment variables for your workflows, tools, and agents. Variables can be set at multiple levels following Compozy's configuration precedence.

config:
  env:
    API_URL: "https://api.example.com"
    API_KEY: "{{ .env.EXTERNAL_API_KEY }}"
    SECRET: "{{ .secrets.API_SECRET }}"

Environment variables are injected into:

• Tool runtime environments with controlled permissions
• Agent configurations for API keys and settings
• Task execution contexts via template variables

For sensitive data, follow security best practices and use the secrets system. Configure environment variables in your project setup or global configuration.

Triggers

Triggers enable workflows to automatically start when specific events occur in your system. The most common trigger type is signal, which creates a publish-subscribe pattern where workflows react to named events.

triggers:
  - type: signal
    name: user-registration
    schema:
      type: object
      properties:
        userId:
          type: string
        email:
          type: string
          format: email
      required: [userId, email]

When a signal is sent (either through the Event API or from a Signal Task), any workflow listening for that signal name will automatically start with the signal payload as input.

Scheduling

Schedule workflows to run automatically at specific times using cron expressions. Compozy leverages Temporal's scheduling engine to provide reliable, distributed scheduling with timezone support and overlap handling.

schedule:
  cron: "0 9 * * *"  # Daily at 9 AM
  timezone: "America/New_York"
  overlap_policy: skip  # skip, allow, buffer_one, cancel_other
  input:
    mode: "scheduled"

The overlap_policy controls behavior when a scheduled run starts before the previous one completes:

• skip - Skip the overlapping run
• allow - Run in parallel
• buffer_one - Queue one run
• cancel_other - Cancel the previous run

Schema Definitions

Define reusable JSON Schema validators within your workflow to ensure consistent data validation across inputs, outputs, and intermediate data structures.

schemas:
  - id: customer_data
    type: object
    properties:
      email:
        type: string
        format: email
      name:
        type: string
    required: [email, name]

Reference schemas using Compozy's $ref syntax:

config:
  input:
    $ref: "local::schemas.#(id==\"customer_data\")"

Schemas integrate with the broader YAML Template System and support all JSON Schema features. Learn more about reference patterns.

MCP Servers

Configure Model Context Protocol (MCP) servers to extend your AI agents with external tools and integrations. MCP provides a standardized way for agents to interact with databases, APIs, file systems, and custom tools.

mcps:
  - id: knowledge-base
    url: "http://localhost:8080/mcp"
    proto: "2025-03-26"
    env:
      API_KEY: "{{ .secrets.MCP_KEY }}"

MCP servers connect through Compozy's MCP Proxy Server (port 6001) which handles authentication, connection management, and protocol translation. Learn about MCP integration patterns and transport configuration.

Outputs

Define the structure and content of data returned when a workflow completes. Outputs use template expressions to aggregate and transform results from tasks, making it easy to create API-friendly response structures.

outputs:
  workflow_id: "{{ .workflow.id }}"
  result: "{{ .tasks.process.output }}"
  status: "{{ .tasks.validate.output.valid ? 'success' : 'failed' }}"

Access data through template variables:

• Task outputs: {{ .tasks.TASK_ID.output }}
• Workflow metadata: {{ .workflow.id }}, {{ .workflow.runId }}
• Conditional logic: Ternary operators and Sprig functions

For advanced output patterns, see Template Advanced Patterns.

Complete Workflow Examples

Related Documentation