Воркфлоу

🔵 Воркфлоу — декларативные многошаговые пайплайны поверх агентов и инструментов. Каждый воркфлоу — YAML-файл в config/workflows/, описывающий упорядоченный список шагов, работающих с накапливающимся скоупом переменных (payload input плюс output_key каждого шага).

Шаги hot-reload'ятся; запуск — POST /v1/workflows/<name>/run.

12.1 Типы шагов

Шаблоны — MiniJinja ({{ var }}, {% if %}), рендерятся от скоупа переменных; {{ x | tojson }} встраивает структурированные значения, env_var('NAME') читает переменную окружения.

12.2 Пример

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 Справочник шагов

agent

Без output_schema вывод шага — текст финального ответа агента. С ним шаг падает, если агент не вернул валидный структурированный результат.

tool

condition

for_each

Каждая итерация работает с копией родительского скоупа + item. Её выводы становятся per-item результатом в results (массив), который collect может переформатировать.

saga

Упорядоченная группа сайд-эффектных инструментов с компенсациями: каждый forward-шаг может объявить compensate, и падение шага откатывает уже выполненные шаги в обратном порядке. Шаги персистятся в durable outbox, поэтому зависшая сага переживает рестарт. Значение шага — массив результатов forward-шагов.

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 }}" }

При падении charge_card ядро вызовет release_stock и пометит шаг compensated; шаг саги завершится ошибкой (saga '…' failed and was rolled back).

loop

Внутренний цикл: повторяет body до тех пор, пока until не отрендерится в true, но не более max_iterations.

Выводы body накапливаются в скоупе цикла и переносятся в родительский скоуп после завершения (поэтому until после каждой итерации видит свежий 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

Проверка одного или нескольких условий. В отличие от остальных шагов, неуспех проверки — не ошибка шага: возвращается { "passed": false, "checks": [...] }, чтобы на него можно было ветвиться (например, в until цикла).

Для проверки-инструмента expect описывает, как прочитать результат: без expect берётся success инструмента; иначе — pointer (JSON Pointer в data, иначе распарсенный content) плюс equals/truthy. Проверка-агент обязана вернуть структурированный { "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 Контроль доступа

Воркфлоу может объявить шаблоны, которые трогает, — тогда скоупед-оператор запустит его только если эти шаблоны в его скоупе:

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

• Scope::All (полный админ) запускает любой воркфлоу.
• Скоупед-оператор (templates: [...] в auth.admin_tokens) запускает воркфлоу только если все его templates в его скоупе, и видит только такие воркфлоу.
• Воркфлоу без templates — только для админа.

run / get_run возвращают 403 для скоупед-оператора вне его скоупа; list их не показывает.

12.5 Триггеры

Воркфлоу может стартовать без явного API-вызова:

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

Запуски пишутся в logs/workflows.db (workflow_runs); статус running → success / error, с per-step записями (id, status, output, error, retries, timings). Состояние между рестартами не персистится — только история запусков.

12.7 Запуск из агентов и инструментов

Воркфлоу можно запустить из другого агента через workflow_tool:

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

Аргументы: workflow (имя, опционально при конфиге) и input (объект). Инструмент возвращает run id; запуск продолжается асинхронно.

12.8 Локальное тестирование

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-шаги работают со встроенными + YAML-инструментами из config/agents/; agent-шаги используют провайдер из config/server.yaml (или DEEPSEEK_API_KEY). Запускай из корня репозитория, чтобы config/ резолвился.

12.9 Примечания

• Поток управления. Шаги идут по порядку; condition прыгает на id then/else, выполнение продолжается оттуда. Шаг с next прыгает на него вместо следующего по списку — используй next, чтобы закрыть if-ветку и пропустить else. Прыжки защищены от бесконечных циклов.
• for_each по пустому массиву — no-op (шаг успешен с []).
• Упавший шаг валит весь запуск; retry применяется к шагу до этого.
• Стейтфул-сессии. Дай двум и более agent-шагам один ключ session — они поделят один разговор: первый создаёт сессию (лениво), следующие её переиспользуют. Сессия закрывается, когда заканчивается охватывающий скоуп. Каждая итерация for_each получает свою сессию на ключ.
• output_schema шага agent переиспользует тот же контракт структурированного завершения, что и агенты (см. §4): схема заменяет параметры job_done, а проверенные аргументы становятся результатом.

12.10 Долговечность (durable)

По умолчанию состояние запуска живёт только в памяти: при рестарте незавершённый запуск теряется (остаётся running в истории). Флаг durable: true включает журнал запуска — движок коммитит scope и позицию на каждой границе шага (для loop — на каждой итерации), а на старте сервера недоделанные запуски перезапускаются с последней границы (logs/workflows.db, таблица workflow_run_state).

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

Семантика — at-least-once (как у durable-сессий и outbox): незавершённый шаг или итерация переигрываются целиком, поэтому сайд-эффекты шагов должны быть идемпотентны (поле idempotency_key у tool-шага или saga). Вложенные шаги внутри loop доигрываются с начала текущей итерации, а for_each — только с незавершённых элементов (выполненные элементы берутся из журнала и не переигрываются).

• budget задаёт лимит общей группы wf:<run_id>, которую используют все агент-шаги запуска; её потраченный итог входит в журнал, поэтому после перезапуска лимит не сбрасывается. durable-запуск получает такую группу всегда (без лимита, если budget не задан) — для учёта стоимости (токенов).
• Идемпотентность. У durable-запуска tool-шаг без явного idempotency_key получает стабильный ключ wf:<run_id>:<шаг>:<итерация>: при переигрывании границы повторный сайд-эффект дедуплицируется side-effect-хранилищем (нужен logging.side_effect_db_path/outbox — иначе дедуп живёт только в памяти). Явный idempotency_key имеет приоритет.
• Дедлайн запуска. timeout_secs ограничивает время всего запуска: на границе шага запуск останавливается со статусом timeout. Абсолютный дедлайн восстанавливается из времени старта в журнале, поэтому перезапуск не продлевает лимит.
• Запуск, превысивший лимит попыток восстановления (3), помечается error («resume limit exceeded») и больше не переигрывается — это карантин «ядовитого» запуска.
• Требует включённого logging.workflow_db_path (по умолчанию logs/workflows.db).

12.11 Харнесс (изолированный workspace)

Блок harness: превращает воркфлоу во «внутренний харнесс» — durable-запуск с циклом (loop/verify) в изолированной рабочей директории. Пример: починка дефекта из тикета.

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 }

• Движок на старте готовит workspace и кладёт в скоуп переменную workspace ({ path, kind, branch, repo }) — шаги адресуют её как {{ workspace.path }}.
• git_worktree: отдельная ветка harness/<run_id> от base; правки агента изолированы и видны как diff, ветка остаётся после очистки как артефакт.
• cleanup: on_success удаляет при успехе, always — всегда, never — сохраняет для разбора.
• Workspace привязан к durable-журналу: после рестарта запуск переподключает ту же директорию/ворктри (prepare идемпотентен).
• Workspace-инструменты. Путь рабочей директории передаётся агент-шагам как template_vars[code_root], поэтому инструменты модуля code (read_file, write_file, edit_file, list_files, grep, run_command) работают внутри изолированного workspace, а не в cwd сервера.
• Артефакты: перед очисткой движок собирает из workspace git status, git diff --stat и git diff (для git-ворктри) и кладёт в read-model; /harness показывает diff запуска.
• Наблюдаемость: страница /harness и API GET /v1/harness/runs, GET /v1/harness/runs/:id (модуль harness, logs/harness.db). Деталь запуска показывает таймлайн шагов/итераций (из событий workflow), стоимость (токены), число итераций, workspace и артефакты.
• Сводка: GET /v1/harness/summary?window_secs= — success/failure rate, средние итерации/длительность, суммарные токены и глубина очереди work items; на странице выводится полосой карточек.
• Метрики на GET /metrics: harness_runs_<status>_total, harness_run_duration_ms, harness_run_iterations, harness_run_tokens_total, harness_work_items_<status> (глубина очереди).

12.12 Work items

Work item — нормализованная единица работы харнесса (тикет, платёж, инцидент). Дедуплицируется по (source, external_id); жизненный цикл: new → claimed → running → done | failed | escalated.

Источники (Jira/GitHub/почта/вебхук) шлют ingest — повторный ingest того же (source, external_id) обновляет содержимое, но не сбрасывает статус:

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

API (модуль harness, таблица harness_work_items):

По завершении связанного запуска статус item обновляется автоматически: success → done, cancelled → new (возврат в очередь), иначе failed.

12.13 Реестр харнессов

Набор харнессов задаётся реестром — файлами config/harnesses/<id>.yaml. Харнесс — это домен-агностичный внутренний цикл (loop/verify), не обязательно про код; workspace опционален. Реестр связывает человеческое описание с workflow'ом-исполнителем и источником работы.

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 — список определений (виден на /harness).
• Маршрутизация: при ingest work item подбирается первый включённый харнесс, чей source.kind (и filter) совпал; при auto_run: true запуск стартует сам, иначе — через POST /v1/harness/work-items/:id/run.
• Грузится при старте из config/harnesses/ (каталог рядом с config/workflows/).
• Operator-тулы для инженера (агент admin, через tool_call): harness_list, harness_toggle, harness_summary, harness_runs, harness_work_items, harness_ingest, harness_run_item — в config/agents/toolbox/tools/.