Flows

Flows orchestrate multi-step workflows with parallel execution, conditional branching, and error handling. Define your workflow in YAML, and ayo handles the rest.

Why Use Flows?

Declarative — Define what, not how
Parallel execution — Independent steps run simultaneously
Dependencies — Automatic ordering based on step relationships
Reusable — Run the same flow with different inputs

Create a Flow

ayo flow new document-pipeline

This creates ~/.config/ayo/flows/document-pipeline.yaml.

Flow Structure

                name: document-pipeline
description: Process incoming documents

steps:
  - name: classify
    agent: "@classifier"
    prompt: "Classify document type: {{.input.file}}"
    
  - name: extract
    agent: "@extractor"
    depends_on: [classify]
    prompt: |
      Document type: {{.steps.classify.output.type}}
      Extract key fields from: {{.input.file}}
    
  - name: validate
    agent: "@validator"
    depends_on: [extract]
    prompt: "Validate extracted data: {{.steps.extract.output}}"
    
  - name: file
    agent: "@filer"
    depends_on: [validate]
    prompt: |
      File document based on:
      Type: {{.steps.classify.output.type}}
      Data: {{.steps.extract.output}}
            

Run a Flow

ayo flow run document-pipeline '{"file": "invoice.pdf"}'

Output:

                ✓ classify: invoice
✓ extract: vendor=Acme, amount=$1,234.56, date=2024-01-15
✓ validate: passed
✓ file: /accounting/2024/q1/invoice_20240115_acme.pdf
            

Step Properties

Property	Description
`name`	Unique identifier for the step
`agent`	Agent to execute this step (@name)
`prompt`	Instructions for the agent
`depends_on`	List of steps that must complete first
`parallel`	Run alongside other parallel steps (true/false)

Variables

Access input and previous step outputs in prompts:

{{.input.fieldname}} — Input data
{{.steps.stepname.output}} — Output from a previous step
{{.steps.stepname.output.field}} — Specific field from output

Parallel Execution

Steps without dependencies run in parallel. Use parallel: true to force parallelism:

                steps:
  - name: grammar
    agent: "@editor"
    prompt: "Review for grammar"
    
  - name: factcheck
    agent: "@researcher"
    prompt: "Verify facts"
    parallel: true  # Runs alongside grammar
    
  - name: legal
    agent: "@compliance"
    prompt: "Check legal issues"
    parallel: true  # Runs alongside grammar and factcheck
    
  - name: synthesize
    agent: "@reviewer"
    depends_on: [grammar, factcheck, legal]
    prompt: "Compile all reviews"
            

List Flows

ayo flow list

View Flow Details

ayo flow show document-pipeline

Example: Content Review Pipeline

                name: content-review
description: Multi-stage content review before publication

steps:
  - name: grammar
    agent: "@editor"
    prompt: "Review for grammar and style: {{.input.content}}"
    
  - name: factcheck
    agent: "@researcher"
    prompt: "Verify all claims: {{.input.content}}"
    parallel: true
    
  - name: legal
    agent: "@compliance"
    prompt: "Check for legal issues: {{.input.content}}"
    parallel: true
    
  - name: synthesize
    agent: "@reviewer"
    depends_on: [grammar, factcheck, legal]
    prompt: |
      Compile final review:
      Grammar: {{.steps.grammar.output}}
      Facts: {{.steps.factcheck.output}}
      Legal: {{.steps.legal.output}}
            

Next Steps

Triggers — Schedule flows automatically
Flows Specification — Complete YAML reference