Workflows

🔵 Workflows are declarative multi-step pipelines on top of agents and tools. Each workflow is a YAML file in config/workflows/ describing an ordered list of steps that operate on an accumulating variable scope (the payload input plus the output_key of each step).

Steps are hot-reloaded; execution is via POST /v1/workflows/<name>/run.

12.1 Step types

Templates are MiniJinja ({{ var }}, {% if %}), rendered from the variable scope; {{ x | tojson }} embeds structured values, env_var('NAME') reads an environment variable.

12.2 Example

name: triage
description: Просмотреть входящие коммиты и завести тикеты.
steps:
  - id: fetch
    type: tool
    tool: git_commits
    args: { since: "{{ input.since | default('yesterday') }}" }
    output_key: commits

  - id: process
    type: for_each
    over: commits.items          # dot-path в скоуп переменных → массив
    item: commit                 # переменная цикла
    concurrency: 3
    max_items: 100
    steps:
      - id: analyze
        type: agent
        template: review
        prompt: "Отревьюй {{ commit.sha }}: {{ commit.message }}"
        output_key: review
        output_schema:
          type: object
          properties:
            needs_action: { type: boolean }
            summary: { type: string }
          required: [needs_action, summary]
        retry: { max: 2, backoff_secs: 5 }
        timeout_secs: 120
      - id: branch
        type: condition
        when: "{{ review.needs_action }}"
        then: file_ticket
      - id: file_ticket
        type: tool
        tool: send_report
        args: { body: "{{ review.summary }}" }
    collect:
      reviews: "{{ results | tojson }}"

  - id: done
    type: tool
    tool: send_report
    args: { body: "{{ reviews }}" }

12.3 Step reference

agent

Without output_schema, the step's output is the text of the agent's final answer. With it, the step fails if the agent did not return a valid structured result.

tool

condition

for_each

Each iteration works on a copy of the parent scope + item. Its outputs become the per-item result in results (an array), which collect can reformat.

saga

An ordered group of side-effecting tools with compensations: each forward step can declare compensate, and if a step fails, the already completed steps are rolled back in reverse order. Steps are persisted to a durable outbox, so a stuck saga survives a restart. The step's value is an array of the forward steps' results.

steps:
  - id: checkout
    type: saga
    saga_id: order-{{ input.order_id }}
    output_key: checkout
    steps:
      - tool: reserve_stock
        args: { sku: "{{ input.sku }}", qty: 1 }
        compensate: { tool: release_stock, args: { sku: "{{ input.sku }}", qty: 1 } }
      - tool: charge_card
        args: { amount: "{{ input.amount }}", key: "{{ input.order_id }}" }

If charge_card fails, the core will call release_stock and mark the step compensated; the saga step will fail with an error (saga '…' failed and was rolled back).

loop

Inner loop: repeats body until until renders to true, but no more than max_iterations.

The outputs of body accumulate in the loop's scope and are carried into the parent scope after completion (so until after each iteration sees the fresh verification).

steps:
  - id: fix
    type: loop
    max_iterations: 8
    until: "{{ verification.passed }}"
    on_max: fail
    body:
      - id: act
        type: agent
        template: bugfix-agent
        prompt: "Исправь дефект (попытка {{ iteration }}): {{ input.summary }}"
        output_key: attempt
      - id: check
        type: verify
        tool: run_tests
        args: { cmd: "cargo test" }
        output_key: verification

verify

Checks one or more conditions. Unlike the other steps, a failed check is not a step error: it returns { "passed": false, "checks": [...] }, so that you can branch on it (e.g. in a until of a loop).

For a tool check, expect describes how to read the result: without expect, the tool's success is taken; otherwise — pointer (JSON Pointer into data, otherwise the parsed content) plus equals/truthy. An agent check must return a structured { "passed": bool }.

  - id: v
    type: verify
    require: all
    output_key: verification
    checks:
      - type: tool
        tool: run_tests
        args: { cmd: "cargo test" }
        expect: { pointer: /passed, equals: true }
      - type: agent
        template: reviewer
        prompt: "Проверь изменения: {{ diff }}"
        output_schema:
          type: object
          properties: { passed: { type: boolean }, reason: { type: string } }
          required: [passed]

12.4 Access control

A workflow can declare the templates it touches — then a scoped operator will only run it if those templates are in their scope:

name: reports
templates: [rss-agent, summarizer]   # шаблоны, которые воркфлоу может трогать
steps: [ ... ]

• Scope::All (full admin) can run any workflow.
• A scoped operator (templates: [...] in auth.admin_tokens) can run a workflow only if all of its templates are in their scope, and only sees such workflows.
• A workflow without templates is admin-only.

run / get_run return 403 for a scoped operator outside their scope; list does not show them.

12.5 Triggers

A workflow can start without an explicit API call:

name: reports
triggers:
  cron:
    - schedule: "0 0 9 * * *"        # cron: sec min hour dom month dow (UTC)
      input: { topic: daily }         # фиксированный input (по умолчанию {})
  webhook:
    token_env: WF_REPORTS_TOKEN       # опциональный bearer (рекомендуется)
steps: [ ... ]

12.6 HTTP API

Runs are written to logs/workflows.db (workflow_runs); status running → success / error, with per-step records (id, status, output, error, retries, timings). State is not persisted across restarts — only the run history.

12.7 Launching from agents and tools

A workflow can be launched from another agent via workflow_tool:

kind: workflow_tool
name: run_triage
description: Запустить воркфлоу триажа.
workflow: triage            # дефолтный воркфлоу (перекрывается аргументом `workflow`)

Arguments: workflow (name, optional when configured) and input (object). The tool returns a run id; the run continues asynchronously.

12.8 Local testing

agent-os module workflow run config/workflows/smoke.yaml '{"items":["Cargo.toml","README.md"]}'
# или input из файла (удобно на Windows):
agent-os module workflow run config/workflows/agent_demo.yaml --args-file args.json

tool-steps work with built-in + YAML tools from config/agents/; agent-steps use the provider from config/server.yaml (or DEEPSEEK_API_KEY). Run from the repository root so that config/ resolves.

12.9 Notes

• Control flow. Steps proceed in order; condition jumps to the id then/else, and execution continues from there. A step with next jumps to it instead of the next one in the list — use next to close an if branch and skip else. Jumps are protected against infinite loops.
• for_each over an empty array is a no-op (the step succeeds with []).
• A failed step fails the entire run; retry applies to the step before it.
• Stateful sessions. Give two or more agent-steps the same session key — they will share a single conversation: the first creates the session (lazily), the following ones reuse it. The session is closed when the enclosing scope ends. Each iteration of for_each gets its own session per key.
• output_schema of step agent reuses the same structured completion contract as agents (see §4): the schema replaces the job_done parameters, and the validated arguments become the result.

12.10 Durability (durable)

By default, run state lives only in memory: on restart, an unfinished run is lost (only running remains in the history). The durable: true flag enables a run journal — the engine commits scope and the position at each step boundary (for loop — at each iteration), and on server startup, unfinished runs are restarted from the last boundary (logs/workflows.db, table workflow_run_state).

name: long-harness
durable: true
budget:                                  # опциональный бюджет на весь запуск
  max_per_turn: 8000
  max_per_minute: 60000
  max_total: 500000
steps: [ ... ]

The semantics are at-least-once (like durable sessions and outbox): an unfinished step or iteration is replayed in full, so step side effects must be idempotent (the idempotency_key field of a tool-step or saga). Nested steps inside loop are replayed from the start of the current iteration, while for_each — only from unfinished elements (completed elements are taken from the journal and are not replayed).

• budget sets the limit of the shared group wf:<run_id> used by all agent steps of the run; its spent total is included in the journal, so after a restart the limit is not reset. A durable run always gets such a group always (without a limit, if budget is not set) — for cost (token) accounting.
• Idempotency. For a durable run, a tool-step without an explicit idempotency_key gets a stable key wf:<run_id>:<шаг>:<итерация>: when a boundary is replayed, the repeated side effect is deduplicated by the side-effect store (requires logging.side_effect_db_path/outbox — otherwise dedup lives only in memory). An explicit idempotency_key takes priority.
• Run deadline. timeout_secs limits the time of the entire run: at step boundary, the run stops with status timeout. The absolute deadline is restored from the start time in the journal, so a restart does not extend the limit.
• A run that exceeds the recovery attempt limit (3) is marked error ("resume limit exceeded") and is no longer replayed — this is quarantine for a "poison" run.
• Requires logging.workflow_db_path to be enabled (by default logs/workflows.db).

12.11 Harness (isolated workspace)

The harness: block turns a workflow into an "internal harness" — a durable run with a loop (loop/verify) in an isolated working directory. Example: fixing a defect from a ticket.

name: jira-bugfix
durable: true
harness:
  workspace:
    kind: git_worktree       # или dir
    repo: "."
    base: origin/main
    cleanup: on_success      # on_success (по умолчанию) | always | never
triggers:
  webhook: { token_env: JIRA_HOOK_TOKEN }
steps:
  - id: fix
    type: loop
    max_iterations: 8
    until: "{{ verification.passed }}"
    body:
      - { id: act,   type: agent,  template: bugfix-agent,
          prompt: "Исправь: {{ input.summary }}", session: fix }
      - { id: check, type: verify, tool: run_tests,
          args: { cmd: "cargo test" }, output_key: verification }

• At startup, the engine prepares the workspace and puts a variable workspace ({ path, kind, branch, repo }) into scope — steps address it as {{ workspace.path }}.
• git_worktree: a separate branch harness/<run_id> from base; the agent's edits are isolated and visible as a diff, the branch remains after cleanup as an artifact.
• cleanup: on_success deletes on success, always — always, never — preserves for analysis.
• The workspace is tied to the durable journal: after a restart, the run reconnects to the same directory/worktree (prepare is idempotent).
• Workspace tools. The working directory path is passed to agent steps as template_vars[code_root], so the tools of the code module (read_file, write_file, edit_file, list_files, grep, run_command) work inside the isolated workspace, not in the server's cwd.
• Artifacts: before cleanup, the engine collects git status, git diff --stat, and git diff from the workspace (for a git worktree) and puts them into the read-model; /harness shows the run's diff.
• Input/output artifacts. In the harness: block you can declaratively declare sources (rendered at startup from input + workspace), results (at finish — also from output_key of the steps), and materials (inline content). An artifact has { kind, title, url?, content? }; an empty render (url/title/content are empty) is discarded. The UI (/harness) renders three blocks — Sources / Results / Materials — generically: url → link, otherwise title copyable, content → collapsible block. Captured diff/status from the provisioner land in materials automatically.
• Run notifications. In the harness definition (config/harnesses/<id>.yaml), the notify: block sends event messages to any channels (universally — the same sinks as cron): events selects WHAT to send (started | finished | failed, by default [finished, failed]), and sinks — WHERE (format CronSink: yandex_messenger, telegram, vk, email, webhook, channel, push, …). Delivery goes through the shared outbound fan-out; the message is assembled from the run's artifacts (source task, status, tokens, MR link).
• Observability: the /harness page and the GET /v1/harness/runs API, GET /v1/harness/runs/:id (module harness, logs/harness.db). The run detail shows a timeline of steps/iterations (from workflow events), cost (tokens), iteration count, workspace, and artifacts.
• Summary: GET /v1/harness/summary?window_secs= — success/failure rate, average iterations/duration, total tokens, and work item queue depth; displayed on the page as a strip of cards.
• Metrics at GET /metrics: harness_runs_<status>_total, harness_run_duration_ms, harness_run_iterations, harness_run_tokens_total, harness_work_items_<status> (queue depth).

12.12 Work items

A work item is a normalized unit of harness work (ticket, payment, incident). Deduplicated by (source, external_id); lifecycle: new → claimed → running → done | failed | escalated.

Sources (Jira/GitHub/email/webhook) send an ingest — re-ingesting the same (source, external_id) updates the content but does not reset the status:

POST /v1/harness/work-items
{ "source": "jira", "external_id": "PROJ-123",
  "title": "Fix login", "body": "...", "priority": 2, "metadata": { } }

API (module harness, table harness_work_items):

When the linked run completes, the item's status is updated automatically: success → done, cancelled → new (return to queue), otherwise failed.

12.13 Harness registry

The set of harnesses is defined by a registry — config/harnesses/<id>.yaml files. A harness is a domain-agnostic internal loop (loop/verify), not necessarily about code; workspace is optional. The registry links a human-readable description to the executor workflow and the work source.

id: jira-bugfix
title: Bugfix из тикета
description: |
  Забирает дефект, воспроизводит, чинит в изолированном workspace,
  прогоняет тесты и отдаёт на ревью.
workflow: jira-bugfix          # workflow с блоком harness:
enabled: true
source:
  kind: jira                   # какой источник кормит (* = любой)
  auto_run: true               # новый work item запускает харнесс сам
  filter: { project: PROJ }    # опц. равенство по metadata work item
defaults: { priority: 1 }      # опц. значения по умолчанию

• GET /v1/harness/harnesses — list of definitions (visible at /harness).
• Routing: on work item ingest, the first enabled harness whose source.kind (and filter) matches is selected; with auto_run: true the run starts on its own, otherwise — via POST /v1/harness/work-items/:id/run.
• Loaded at startup from config/harnesses/ (a directory next to config/workflows/).
• Operator tools for the engineer (agent admin, via tool_call): harness_list, harness_toggle, harness_summary, harness_runs, harness_work_items, harness_ingest, harness_run_item — in config/agents/toolbox/tools/.