Робочі процеси в інструкціях
Простими словами: робочий процес — це процес, записаний як іменовані кроки. Кожен крок каже, що відбувається (агент готує чернетку, викликається інструмент, вирішує людина) і які кроки мають завершитися перед ним. Перші два розділи показують усю ідею; решта — це повна мова, на той випадок, коли вона знадобиться.
Це переклад довідника зі специфікації. Нормативним є англійський текст; ключові слова, назви полів і приклади залишено такими, як в оригіналі.
Діалект: instruction/workflow. Редакція: 1.
Стан: робоча чернетка першої редакції. Це власна частина instruction.md.
Дата: 2026-10-28.
Робочі процеси в інструкціях (Instruction Workflows) описують багаторазові процеси як іменовані типізовані кроки. Мова охоплює тригери, потік даних, виклики моделей та інструментів, умовні маршрути, паралельну роботу, рішення людини, тривалі очікування, відновлення та кінцеві результати. Початкову мову надав AgentD; тепер вона описана тут незалежно від будь-якого середовища виконання. Реалізація оголошує, які види вузлів і які можливості виразів, ідентичності, зберігання та інтеграцій вона підтримує.
Схема робочого процесу та реєстр вузлів є нормативними машиночитаними частинами цього довідника. Реєстр зберігає всі 74 імпортовані види, зокрема 11 видів тригерів. Перевірка за схемою — це лише один рівень перевірки; вимоги до графа й поведінки, наведені нижче, теж діють. Рендерер не є хостом робочих процесів.
Оголошення робочого процесу
:::workflow{id=brief dialect="instruction/workflow"}
name: morning-brief
steps:
start:
kind: manual
draft:
kind: agent
depends_on: [start]
instruction: Prepare a concise daily brief. Preserve uncertainty.
review:
kind: human
depends_on: [draft]
question: Accept this brief?
schema: { type: string, enum: [accept, revise] }
route:
kind: switch
depends_on: [review]
on: "{{ steps.review.output }}"
cases: { accept: accepted, revise: revision }
accepted:
kind: finish
depends_on: [route]
output: "{{ steps.draft.output }}"
revision:
kind: finish
depends_on: [route]
status: cancelled
reason: The reviewer requested a revision.
:::
Зовнішній id — це ідентичність об’єкта інструкції; name — ідентичність
робочого процесу в межах його хоста. dialect вибирає цей контракт. YAML і
JSON — рівнозначні подання тієї самої моделі. Повторювані ключі відображення є
помилками. Структуроване тіло робочого процесу є буквальним: директиви Markdown
і підстановки ${parameter} інструкції всередині нього не діють. Шаблони
робочого процесу {{ … }} мають значення, описані нижче.
Відкриття, розбір, розв’язання посилань, компіляція чи відображення інструкції MUST NOT (не повинні) вмикати тригери, реєструвати інструменти, відкривати маршрути, надсилати повідомлення або починати запуск. Активація — це явна операція хоста після перевірки й авторизації.
Поля визначення
| Поле | Значення |
|---|---|
name |
Обов’язковий ідентифікатор, 1–64 символи, що відповідає [A-Za-z_][A-Za-z0-9_-]* |
steps |
Обов’язкове відображення ідентифікаторів кроків на типізовані визначення |
description |
Призначення, зрозуміле людині; його можна використати і як опис зареєстрованого інструмента |
armed |
Чи може явно активоване визначення вмикати свої тригери; типово true |
inputs.schema, outputs.schema |
Схеми вхідних даних запуску та кінцевого результату |
concurrency |
max_runs, on_overflow (queue, drop, replace) і scope (workflow, key) |
key |
Шаблон часу спрацювання тригера, який визначає сутність, якої стосується запуск; обов’язковий для одночасності в межах ключа |
limits |
Кроки, токени, крайній термін і бюджет на один запуск |
priority |
low, normal або high; побажання щодо планування, а не надання дозволу |
durable |
Чи переживає стан запуску процес хоста; false явно дозволяє запуски лише в пам’яті |
state |
Оголошені схеми змінних запуску та редуктори одночасного запису |
unload |
Політика виведення з роботи: drain, cancel або detach, з необов’язковим часом очікування |
tool |
Пропонований інтерфейс робочого процесу, який можна викликати: назва, синхронний чи асинхронний режим і дозволи для тих, хто викликає |
act_for |
Пропонований делегований учасник і механізм згоди; потрібне схвалення оператора |
Невідомі стандартні поля й невідомі назви видів є помилками. Поля з простором
імен x-* можуть містити оголошені дані розширень. Хост MUST (повинен)
повідомити про непідтримуване розширення, яке впливає на поведінку, а не мовчки
його відкинути. Директиви конфігурації, які завантажують файл, URL, теку або
ресурс MCP, належать до конфігурації хоста; вони не є альтернативними
визначеннями робочого процесу.
Вхідні дані перевіряються до допуску. Неправильні вхідні дані не створюють
запуску. Готові результати мають відповідати outputs.schema; невідповідність
схемі не є успішним завершенням. Обмеження ресурсів і допуск за одночасністю
мають бути записані у профілі виконання запуску, щоб результат можна було
переглянути.
Графи, області та перевірка
Граф залежностей є ациклічним. Ідентифікатори кроків унікальні в межах області.
Кожен крок верхнього рівня має бути досяжним від тригера через залежності або
явні ребра маршрутизації. Граф верхнього рівня потребує щонайменше одного
тригера й одного finish. Назви залежностей, цілі перемикача, цілі для помилок
і цілі для вичерпаного часу мають існувати в тій самій області. Значення
варіантів перемикача називають один крок рядком, а не список.
foreach, batch, iterate і subgraph містять body: {steps: …}.
parallel і race містять іменовані branches, кожна зі своїми steps.
Залежності всередині тіла називають сусідні кроки. Вкладені області не можуть
містити тригерів чи finish; їхнім результатом є їхні кінцеві кроки. Найбільша
вкладеність — чотири рівні тіла, а визначення верхнього рівня містять не більш
як 512 кроків. Згенеровані ідентифікатори екземплярів позначають ітерацію або
гілку, наприклад each[0].draft, parallel{research}.fetch або sub.review.
Реалізація має перевірити типи, обов’язкові поля кожного виду, області, посилання, досяжність, цикли, можливості виразів і обмеження до активації. JSON Schema навмисно залишає деякі значення даних адаптерів відкритими; вона не перевіряє аргументи віддаленого інструмента, усі шляхи виразів, авторизацію чи поведінку під час виконання. Для цих перевірок потрібні контракти відповідного хоста та інтеграцій. Обов’язкові непідтримувані види є помилкою, а не порожньою операцією.
Тригери
Реєстр містить once, manual, loop, schedule, subscribe,
stream, correlate, signal, event, a2a і webhook.
Тригер створює подію для допуску, а не виконує подальшу роботу безпосередньо.
Її дані стають результатом кроку тригера, що спрацював. У запуску спрацьовує
рівно один тригер; сусідні тригери отримують стан skipped і задовольняють
залежності. Відображення inputs тригера використовують простори імен
payload та env часу спрацювання; отримані вхідні дані запуску перевіряються
за inputs.schema.
schedule приймає cron, every або at, рівно одне джерело часу.
Успадкований п’ятипольний діалект cron працює в UTC. Він не отримує неявного
поля tz: для повторень за місцевим календарем можна використати явний діалект
планування окремого блоку schedule. Хости записують політику щодо пропущених
спрацювань і відновлення. loop поєднує інтервал, затримку й поступове
збільшення паузи з умовами завершення та найбільшою кількістю ітерацій. once
і manual відрізняють автоматичну активацію від запуску на запит оператора.
subscribe читає названий ресурс MCP після сповіщень про зміну й може
усувати брязкіт (debounce), фільтрувати та збирати обмежене вікно зразків.
stream споживає збережені події з фільтруванням за темою, зміщеннями та
керуванням частотою й розміром пакетів. correlate групує пов’язані події в
обмеженому вікні з лімітом на стан, що очікує. signal — це сповіщення, яке
спрацьовує за фронтом: його отримують наявні очікувачі, а сигнал, надісланий до
реєстрації очікувача, не буферизується. Коли потрібне зберігання,
використовуйте збережений потік. Події й підписки потребують явної можливості
хоста та автентифікованих прив’язок до джерел.
a2a прив’язує прийняті команди, ролі учасників і схему вхідних даних.
webhook описує вхідний шлях, методи, автентифікацію, частоту й політику
відповіді. Оголошення будь-якого з них ніколи не створює неавтентифікованого
слухача. Хост авторизує та прив’язує їх під час активації.
Спільні поля кроків
Кожен крок має kind. Спільні поля: depends_on, description, when,
timeout, retry, on_error, on_replay, idempotent, output_schema,
budget, cache, skills та otel. Те, що вони є, не означає, що хост
підтримує кожен вузол чи інтеграцію.
timeout обмежує спробу або очікування, властиве вузлу. retry.max рахує
повторні спроби після першої, має значення від нуля до двадцяти, а
retry.backoff задає початкову затримку, яка зростає експоненційно. Пауза між
спробами є тривкою, з обмеженим зростанням і випадковим розкидом. on_error
має значення fail (типово), continue або goto:<step>.
on_replay має значення retry (типово), skip або fail. Хост записує
типові значення та чинні обмеження щодо моделі, інструментів, мережі й бюджету
у профілі запуску.
Поля мережевих вузлів можуть додатково оголошувати breaker: {failures, cooldown},
rate та idempotency. Повторні спроби стосуються невдачі однієї спроби;
запобіжники (breakers) поділяють стан збою між запусками; керування частотою
відкладає роботу, не витрачаючи спроби; ідемпотентність дає змогу розпізнати
повторну доставку. Ці засоби мають різні значення і MUST NOT (не повинні)
зводитися до одного лічильника повторних спроб.
Шаблони та вирази
Рядок, який складається рівно з одного {{ path }}, дає типізоване значення,
на яке він посилається. Рядок із текстом довкола підставляє значення, зберігаючи
рядки й кодуючи інші значення як JSON. {{ path | fallback }} дає запасне
значення лише для відсутнього шляху; наявний null запасного значення не
використовує. Початковий / вибирає шлях JSON Pointer, що корисно для
згенерованих ідентифікаторів із крапками. Відсутні шляхи без запасного значення
спричиняють невдачу спроби.
| Простір імен | Значення |
|---|---|
inputs |
Перевірені вхідні дані запуску |
run |
Ідентичність запуску й робочого процесу, початок, учасник, завдання, спроба і стан |
steps.<id> |
Стан, результат, помилка та спроба кроку; усередині тіла — ідентифікатори сусідніх кроків |
vars |
Оголошені або записані змінні запуску |
env |
Контекст хоста й запуску; для кожного кроку step, attempt і стабільний idempotency_key |
memory |
Явно прив’язані ключі тривкої пам’яті |
item, index, псевдонім as |
Поточний елемент колекції та його індекс |
batch, iteration, branch |
Контекст вкладеного виконання |
CEL: … обчислює вираз CEL. Умова when, умови перевірок, вирази
map/filter/reduce, умови ітерацій і фільтри підписок використовують свої
задокументовані контексти обчислення. Вкладені body та branches, схеми,
відображення цілей перемикача й поля з виразами залишаються буквальними, доки
їх не обчислить їхній власний вузол. Хост без потрібної можливості CEL має
відмовити в активації. Він не може замінити вираз істиною.
when також може використовувати {noul: "statement", state?, model?, confidence?}
для рішення, яке ухвалює модель. Хост подає це рішення як тривкий крок
<id>.when із власним бюджетом. Відповідь «не певна» або з недостатньою
впевненістю означає, що умова не виконана. Чинний поріг рішення має бути явно
вказаний у профілі запуску. Умова правила, написана прозою в інструкції довкола,
відрізняється від цієї виконуваної умови робочого процесу.
Позначки секретів, такі як {{secret:NAME}} і {{secret-file:PATH}},
розв’язуються лише в авторизованих полях інтеграцій, що містять облікові дані.
В інших місцях вони залишаються буквальними. Секрети не стають звичайним
результатом кроку, метаданими документа чи вмістом журналу. Розв’язання
інструкції не читає сховища секретів хоста.
Розгалуження та об’єднання
Хибна умова when верхнього рівня або невибраний маршрут перемикача надає
крокові стан pruned. Крок у стані pruned не задовольняє залежностей. Крок,
усі вхідні шляхи якого мають стан pruned, теж його отримує; щонайменше один
живий шлях залишає об’єднання придатним до виконання. Крок у стані skipped
залежності задовольняє. Ця відмінність дає змогу об’єднувати нерівні гілки.
Вибраний маршрут перемикача, on_error: goto:… або on_timeout можуть
активувати свою ціль, не чекаючи на список її залежностей, але не можуть обійти
її умову when. Ребра маршрутизації можуть повертатися до кроку; граф
залежностей однаково має бути ациклічним, а запуск залишається обмеженим своїми
лімітами. Маршрут відновлення, умова якого не виконана, не стирає початкової
невдачі.
Усередині тіла хибна умова when дає стан skipped, і наступні сусідні кроки
можуть виконуватися далі. Невибрані варіанти перемикача в тілах, як і раніше,
отримують стан pruned. Хости й засоби візуалізації мають зберігати цю
різницю, а не показувати всі неактивні вузли як однакові. Зображення Mermaid не
може перевизначити цю поведінку.
Паралельна, повторювана й делегована робота
parallel виконує іменовані гілки; race вибирає найперший придатний результат
і скасовує роботу, що програла. foreach виконує тіло для кожного елемента з
обмеженими розміром batch, паралелізмом і частотою. batch дає кожному тілу
групу. iterate повторює за умовами while/until з найбільшою кількістю
ітерацій. Політика збирання результатів задається явно через collect. Тіло не
може мовчки успадкувати необмежене розгалуження.
workflow викликає названий дочірній процес у режимі sync, async або
detached; async повертає дескриптор. join чекає на дескриптори з політикою
щодо часу очікування, мінімуму та часткових результатів. cascade керує
скасуванням дочірніх процесів. subagent делегує обмежену роботу з явно
вказаними інструментами, серверами, навичками, контекстом і бюджетами. Вузли
A2A прив’язують названих партнерів, контракти завдань і повідомлень та
очікування завершення. Делегування може звужувати повноваження; оголошення
дочірнього процесу не повинне розширювати чинні дозволи того, хто викликає.
Очікування та рішення людини
wait, sleep, human, очікування дочірніх процесів і паузи між повторними
спробами призупиняють роботу через тривкі записи очікування, а не через потік,
заблокований у пам’яті. Очікування може називати ресурс, подію, сигнал, запуск,
субагента, розмову, вебхук, завдання або іншу зареєстровану умову очікування.
on_timeout — це явна ціль маршрутизації. Крок рішення людини називає питання,
необов’язкову схему відповіді та передбаченого отримувача. Відповіді
перевіряються і прив’язуються до авторизованого учасника; намальована позначка
схвалення чи прапорець, поставлений у документації, не є схваленням.
Реалізація, яка заявляє про тривке виконання, має відновлювати призупинені очікування та їхні крайні терміни. Вона має відрізняти збережене оголошення від активного запуску, а авторську контрольну точку — від записаного рішення людини.
Стани запуску та кроків
Стани запуску: running, paused, completed, failed, refused,
cancelled і stalled. Перші два не є кінцевими. finish визначає кінцевий
стан і результат; якщо немає ні готової роботи, ні роботи в процесі, ні
finish, це стан stalled, або failed, коли блокування спричинила помилка
вище за течією.
Стани кроків: pending, running, suspended, done, skipped, pruned,
failed, timeout і cancelled. Звичайну залежність задовольняють лише
done і skipped. Помилка за on_error: continue завершує крок із записаною
помилкою. Завершення запуску скасовує незавершені кроки. Коди виходу, засоби
збереження та клієнтські протоколи — це справа адаптерів середовища виконання,
а не новий синтаксис Markdown.
Тривкість, ідемпотентність та оновлення
Крок, що має наслідки, записує контрольну точку running перед дією.
Детерміновані кроки з даними можна відтворити від попередньої контрольної
точки. Після аварії дію, яка завершилася на віддаленому боці, але втратила
підтвердження, може бути доставлено знову. Контракт — доставка щонайменше один
раз; це не віддалене виконання рівно один раз.
Типовий ключ ідемпотентності — це перші 32 шістнадцяткові символи
sha256(run_id + "." + step_instance_id), стабільні для повторних спроб і
відтворення цього екземпляра. Оголошений бізнес-ключ може усувати дублікати між
запусками. Щоб дублікати справді усувалися, віддалені інструменти й сервіси
мають зважати на цей ключ. on_replay визначає, що робити з роботою, стан якої
невідомий: повторити, пропустити чи вважати невдалою. Хост не повинен заявляти
про безпечність відтворення лише тому, що ключ було надіслано.
Запуск записує дайджест свого визначення та профіль виконання. Оновлення
чинного визначення впливає на подальші допуски; наявні запуски зберігають своє
закріплене визначення. Відновлення потребує відповідного визначення й не
повинне підставляти найновіший текст. Виведення з роботи застосовує unload і
записує скасування чи завершення розпочатого. Пам’ять, артефакти, зміщення
потоків і контрольні точки тригерів мають різні строки життя. Чутливі артефакти
зберігають засоби контролю доступу хоста й не копіюються мовчки до пакетів
інструкцій.
Каталог вузлів і точки розширення
Повний довідник вузлів згенеровано з власного реєстру; він перелічує обов’язкові й необов’язкові поля кожного імпортованого виду. Він охоплює тригери, керування перебігом, перетворення даних, пам’ять, артефакти, знання, пошук, MCP, HTTP, A2A, обмін повідомленнями, життєвий цикл робочих процесів, операції з моделями, агентів і рішення людини. Постачальники вузлів можуть бути окремими інтеграціями хоста; наявність у мові не обіцяє, що хост має обліковий запис чи реалізацію.
Хости робочих процесів публікують профіль можливостей із видами вузлів, можливостями виразів, межами ресурсів, прив’язками облікових даних та ідентичності й підтримкою тривкості. Нестандартна поведінка використовує оголошені розширення з простором імен, з явними вимогами до схеми й можливостей. Невідома виконувана поведінка ніколи не повинна зводитися до виконання чогось приблизного. Рендерери зберігають джерело й видимо показують непідтримувану семантику; використання лише для відображення може бути корисним і без середовища виконання.
Нестандартний вузол використовує kind: alias:node. Його зовнішня прив’язка
розширення інструкції вибирає точний маніфест і версію; окремий робочий процес
отримує рівнозначні прив’язки з профілю свого хоста. provides.workflow_nodes
у маніфесті розширення зіставляє назви вузлів із role (trigger або step),
схемою вузла schema, контрактом semantics і необов’язковими можливостями
requires. Базова схема робочого процесу може зберегти вузол із простором
імен, але активація додатково перевіряє цей маніфест і його встановленого
постачальника. Метадані джерела ніколи не встановлюють код і не авторизують
постачальника. Обмежений власний засіб перевірки графів у репозиторії відхиляє
такі вузли як непідтримувані, а не заявляє про відповідність хоста розширень.
Перенесення та походження
Початковий реєстр і спільні поля було імпортовано на прохання власника зі
знімка схеми AgentD із SHA-256
40f1d4a06967af70705d1b6aa508ebcc7defc7693ad3e8d8570eb02637ac5f23.
Точний знімок зберігається у відомостях про походження.
Схема instruction.md додає перевірки полів для кожного виду та явну рекурсивну
структуру тіла. Перевірки графа й поведінки залишаються окремими.
agentd/workflow залишається ідентифікатором сумісності адаптера. Нові власні
документи використовують instruction/workflow; профіль AgentD
може експортувати сумісні визначення до AgentD, не переписуючи даних їхніх
кроків. Це перенесення не змінило жодної інсталяції AgentD, конфігурації
сервера, опублікованого сайту чи середовища виконання. Ця робоча чернетка та її
нові тести на відповідність ще потребують незалежного розгляду реалізації
середовища виконання перед остаточним випуском.