Advanced Workflows

Overview

This page covers the control-flow and reliability features of the agent-workflow/v1 DSL, plus several complete, runnable example workflows. If you’re new to the DSL, start with Creating Workflows.

Branching

`if` — conditional tasks

Attach if: to run a task only when a condition is true. When the condition is false, the task and everything downstream of it cascade-skip:

tasks:
  deploy:
    if: inputs.ready          # false → deploy and its dependents skip
    command: ./deploy.sh

Conditions are template expressions evaluated for truthiness — for example inputs.score >= 60, tasks.check.output.exitCode == 0, or a plain boolean input.

`else_of` — the else branch

else_of: runs a task only when the referenced task was condition-skipped. It’s the “else” side of an if:

tasks:
  deploy:
    if: inputs.ready
    command: ./deploy.sh
  notify_skip:
    else_of: deploy           # runs only when `deploy` was skipped by its `if`
    command: osascript -e 'display notification "deploy skipped"'

`run_when: always` — join and cleanup

A task with needs normally skips if any dependency skipped, and the run stops if a required dependency fails. run_when: always overrides both — the task runs as long as its dependencies have finished, whether they succeeded, skipped, or failed. Use it for joins and cleanup:

tasks:
  build:
    command: ./build.sh
  cleanup:
    needs: [build]
    run_when: always          # runs even if `build` failed
    command: rm -rf ./.tmp

Loops

`foreach` — fan out over a list

foreach: runs the task once per item. Inside, {{ item }} is the current element and {{ index }} is its position. Downstream tasks receive the collected array of outputs:

inputs:
  questions: ["What is it?", "Why does it matter?"]
tasks:
  answer:
    foreach: "{{ inputs.questions }}"
    prompt: "Answer in one sentence: {{ item }}"
  digest:
    uses: transform
    value: "{% for a in tasks.answer.output %}- {{ a }}\n{% endfor %}"

foreach also accepts an inline array, and it composes with the other executors (a foreach of tool: calls, of subworkflows, and so on). An empty list produces an empty result and downstream tasks still run.

`loop` — repeat until a condition holds

loop: repeats a task. until: is checked after each round against output (that round’s result); {{ round }} is the round number and {{ last }} is the previous round’s output. Exhausting maxRounds without satisfying until fails the task.

tasks:
  poll:
    run: "curl -s -o /dev/null -w '%{http_code}' https://example.com/status"
    loop:
      until: "output.stdout | trim == '200'"
      maxRounds: 10

Omit until to loop a fixed number of times:

tasks:
  retry_build:
    command: ./build.sh
    loop:
      maxRounds: 3

Reliability

retries — retry a failed task. Either a count (retries: 2) or an object (retries: { maxAttempts: 3, delayMs: 500 }).
required: false — a failure of this task does not abort the run; downstream tasks continue.
timeoutMs — kill a shell task that runs too long.

tasks:
  flaky_fetch:
    tool: web_fetch/web_fetch
    params: { link_url: "{{ inputs.url }}" }
    retries: { maxAttempts: 3, delayMs: 1000 }
  optional_enrich:
    run: "./enrich.sh || exit 1"
    required: false           # failure here won't stop the run

Output contracts — `output_schema`

Attach an output_schema (a JSON Schema object) to a prompt or agent task to enforce the shape of the reply. You do not need to describe the JSON format in the prompt text — the schema is enforced by the model provider and injected as an instruction, and the reply is parsed (with repair) into an object you can index into downstream. If the output doesn’t conform, the task retries; if it never conforms, the task fails.

tasks:
  extract:
    prompt: "Extract the invoice details from: {{ inputs.text }}"
    output_schema:
      type: object
      required: [payer, amount, date]
      properties:
        payer:  { type: string }
        amount: { type: number }
        date:   { type: string }
  record:
    uses: transform
    value: "{{ tasks.extract.output.payer }} paid {{ tasks.extract.output.amount }}"

Per-task model overrides

prompt and agent tasks accept optional provider: and model: to switch the LLM for that task only. This is a run-scoped override — your saved model configuration is untouched. Use a cheap model for bulk steps and a stronger one where it matters:

tasks:
  draft:
    prompt: "Draft a blog outline for: {{ inputs.topic }}"
    provider: enconvo_ai
    model: anthropic/claude-haiku-4-5-20251001
  polish:
    prompt: "Polish this outline into final copy:\n{{ tasks.draft.output }}"
    provider: enconvo_ai
    model: anthropic/claude-sonnet-5

provider is a provider command (e.g. enconvo_ai, open_ai, ollama) and model is a model id for that provider. Both are only valid on prompt/agent tasks.

Subworkflows

Compose workflows with uses: workflow, either by workflowId: (a saved workflow) or an inline workflow: block. The task’s output is the child run result — reference the child’s task outputs via output.outputs.<taskId>:

tasks:
  build_each:
    foreach: "{{ inputs.targets }}"
    uses: workflow
    inputs:
      target: "{{ item }}"
    workflow:
      tasks:
        compile:
          run: "make {{ inputs.target }}"
        package:
          run: "tar czf {{ inputs.target }}.tgz build/"
  summary:
    uses: transform
    value: "{% for r in tasks.build_each.output %}{{ r.status }} {% endfor %}"

Templates reference

Reference	Where
`{{ inputs.x }}`	Anywhere — workflow inputs
`{{ tasks.<id>.output }}`	Anywhere — an upstream task’s output
`{{ item }}` / `{{ index }}`	Inside a `foreach` task
`{{ round }}` / `{{ last }}`	Inside a `loop` task
`{{ now }}`	Current timestamp
`{{ env.HOME }}`	Process environment variables

Templates support Nunjucks filters (| trim, | int, | dump, | default(...), {% for %}, etc.), which is how you reshape data between tasks.

Complete examples

Research → summarize → report

Search the web, summarize the findings, and assemble a Markdown report. Note the sequential-by-default chaining — no needs wiring required:

version: agent-workflow/v1
title: Research Brief
description: Search the web on a topic and produce a short Markdown brief.
inputs:
  topic: coffee brewing
tasks:
  search:
    tool: web_search/web_search
    params:
      search_query: "{{ inputs.topic }} latest"
      limit: 5
  summarize:
    prompt: |
      Summarize the key points from these results in 4 bullets.
      Results: {{ tasks.search.output }}
    provider: enconvo_ai
    model: anthropic/claude-haiku-4-5-20251001
  report:
    uses: transform
    value: |
      # {{ inputs.topic }} — brief ({{ now }})
      {{ tasks.summarize.output }}

Conditional routing

Approve or reject based on a score, then always write a final report:

version: agent-workflow/v1
title: Lead Router
description: Route a lead by score, reporting the outcome either way.
inputs:
  score: 42
tasks:
  approve:
    if: "inputs.score >= 60"
    uses: transform
    value: "approved"
  reject:
    else_of: approve
    uses: transform
    value: "rejected"
  report:
    needs: [approve, reject]
    run_when: always
    uses: transform
    value: "outcome: {{ tasks.approve.output | default('') }}{{ tasks.reject.output | default('') }}"

Loop until converged

Refine a draft repeatedly until a self-check approves it, capping the rounds:

version: agent-workflow/v1
title: Refine Until Good
description: Improve a draft until a self-check approves it.
inputs:
  brief: A tweet announcing our new feature.
tasks:
  refine:
    prompt: |
      Improve this draft. Return the improved draft and whether it is ready.
      Previous attempt: {{ last | default(inputs.brief) }}
    provider: enconvo_ai
    model: anthropic/claude-haiku-4-5-20251001
    output_schema:
      type: object
      required: [draft, approved]
      properties:
        draft:    { type: string }
        approved: { type: boolean }
    loop:
      until: "output.approved == true"
      maxRounds: 4
  publish:
    uses: transform
    value: "{{ tasks.refine.output.draft }}"

Creating workflows

The editor, the editing assistant, and each executor.

Introduction

The task model and how workflows are run.

Getting Started

Core Features

AI Capabilities

Providers

Workflows & Extensions

Integrations

Advanced

Configuration

Resources

Overview

Branching

`if` — conditional tasks

`else_of` — the else branch

`run_when: always` — join and cleanup

Loops

`foreach` — fan out over a list

`loop` — repeat until a condition holds

Reliability

Output contracts — `output_schema`

Per-task model overrides

Subworkflows

Templates reference

Complete examples

Research → summarize → report

Conditional routing

Loop until converged

Creating workflows

Introduction

​Overview

​Branching

​if — conditional tasks

​else_of — the else branch

​run_when: always — join and cleanup

​Loops

​foreach — fan out over a list

​loop — repeat until a condition holds

​Reliability

​Output contracts — output_schema

​Per-task model overrides

​Subworkflows

​Templates reference

​Complete examples

​Research → summarize → report

​Conditional routing

​Loop until converged

​Related

Creating workflows

Introduction

Overview

Branching

`if` — conditional tasks

`else_of` — the else branch

`run_when: always` — join and cleanup

Loops

`foreach` — fan out over a list

`loop` — repeat until a condition holds

Reliability

Output contracts — `output_schema`

Per-task model overrides

Subworkflows

Templates reference

Complete examples

Research → summarize → report

Conditional routing

Loop until converged

Related