Skip to main content

Workflow Specification

OSSA Workflow kind for multi-agent composition

Workflow Specification

The Workflow kind enables composition of multiple agents and tasks into complex, multi-step workflows with dependency management, conditional execution, and error handling.

Overview

Workflows allow you to:

  • Compose multiple agents into coordinated workflows
  • Define execution order with dependencies
  • Handle errors with retry policies and compensation
  • Execute steps conditionally based on state
  • Run steps in parallel for performance
  • Manage state between steps

Manifest Structure

apiVersion: ossa/v0.3.0
kind: Workflow
metadata:
  name: my-workflow
  version: 1.0.0
  description: Multi-agent workflow example
spec:
  steps:
    - id: step1
      kind: Agent
      ref: my-agent
      input:
        query: "Hello"
  triggers:
    - type: webhook
      path: /trigger

Field Reference

Field NameTypeRequiredDescription
apiVersionstringYesOSSA API version. Must be ossa/v0.3.1 or higher for Workflow support
kindstringYesMust be Workflow
metadataMetadataYesWorkflow metadata
specWorkflowSpecYesWorkflow specification

WorkflowSpec Object

Field NameTypeRequiredDescription
stepsarrayYesArray of workflow steps (min 1)
triggersarrayNoWorkflow triggers (webhook, cron, event, manual, message)
inputsobjectNoInput schema (JSON Schema)
outputsobjectNoOutput schema (JSON Schema)
messagingobjectNoAgent-to-agent messaging configuration (v0.3.1+)
contextobjectNoContext variables and secrets
concurrencyobjectNoConcurrency control settings
error_handlingobjectNoError handling configuration
timeout_secondsintegerNoWorkflow timeout (1-86400)
observabilityobjectNoTracing, metrics, and logging configuration

WorkflowStep Object

Each step in a workflow can be one of several kinds:

Field NameTypeRequiredDescription
idstringYesUnique step identifier (pattern: ^[a-z][a-z0-9_-]*$)
kindstringYesStep type: Task, Agent, Parallel, Conditional, Loop
namestringNoHuman-readable step name
refstringNoReference to Agent or Task manifest
inlineobjectNoInline step definition
inputobjectNoStep input (supports ${variable} substitution)
outputobjectNoOutput configuration
conditionstringNoConditional expression (evaluated against workflow state)
depends_onarrayNoArray of step IDs that must complete before this step
parallelarrayNoParallel steps (for kind: Parallel)
branchesarrayNoConditional branches (for kind: Conditional)
elsearrayNoElse branch steps (for kind: Conditional)
loopobjectNoLoop configuration (for kind: Loop)

Step Kinds

Task Step

Execute a deterministic task (non-agentic):

steps:
  - id: publish-content
    kind: Task
    ref: publish-task
    input:
      content_id: "${content.id}"

Agent Step

Invoke an agent:

steps:
  - id: analyze-data
    kind: Agent
    ref: data-analyst-agent
    input:
      dataset: "${input.dataset}"
    output:
      to: analysis_results

Parallel Step

Execute multiple steps concurrently:

steps:
  - id: parallel-analysis
    kind: Parallel
    parallel:
      - id: analyze-code
        kind: Agent
        ref: code-analyzer
      - id: analyze-tests
        kind: Agent
        ref: test-analyzer
      - id: analyze-docs
        kind: Agent
        ref: doc-analyzer

Conditional Step

Execute steps based on conditions:

steps:
  - id: conditional-review
    kind: Conditional
    condition: "${severity} === 'high'"
    branches:
      - condition: "${severity} === 'critical'"
        steps:
          - id: escalate
            kind: Agent
            ref: escalation-agent
      - condition: "${severity} === 'high'"
        steps:
          - id: review
            kind: Agent
            ref: review-agent
    else:
      - id: log
        kind: Task
        ref: log-task

Loop Step

Iterate over a collection:

steps:
  - id: process-items
    kind: Loop
    loop:
      over: "${items}"
      as: item
      index: idx
    # Loop body steps would be defined here

Triggers

Workflows can be triggered by:

Webhook Trigger

triggers:
  - type: webhook
    path: /workflow/trigger
    filter:
      method: POST

Cron Trigger

triggers:
  - type: cron
    schedule: "0 0 * * *"  # Daily at midnight

Event Trigger

triggers:
  - type: event
    source: gitlab
    event: merge_request.created

Manual Trigger

triggers:
  - type: manual

Message Trigger (v0.3.1+)

triggers:
  - type: message
    channel: workflow-events
    filter:
      type: workflow.start

Error Handling

Configure how workflows handle errors:

spec:
  error_handling:
    on_failure: rollback  # halt, continue, rollback, notify, compensate
    retry_policy:
      max_attempts: 3
      backoff: exponential
      initial_delay_ms: 1000
      max_delay_ms: 60000
    compensation_steps:
      - id: cleanup
        kind: Task
        ref: cleanup-task
    notification:
      channels:
        - email
        - slack
      template: "Workflow ${executionId} failed: ${error}"

State Management

Workflow state is managed automatically between steps. Access state using ${variable} syntax:

steps:
  - id: step1
    kind: Agent
    ref: agent1
    output:
      to: result1
  - id: step2
    kind: Agent
    ref: agent2
    input:
      previous_result: "${result1}"

Concurrency Control

Limit concurrent executions:

spec:
  concurrency:
    group: workflow-group-1
    cancel_in_progress: false

Observability

Enable tracing, metrics, and logging:

spec:
  observability:
    tracing:
      enabled: true
      propagate_context: true
    metrics:
      enabled: true
      custom_labels:
        team: engineering
    logging:
      level: info

Examples

See Workflow Examples for complete examples.

Related Documentation