Контракт інструментів агентів

Durable Workflow v2 робить розробку за допомогою AI передбачуваною, надаючи факти продукту через стабільні контракти. Інструмент має читати версію документації, виявляти локальний інтерфейс, викликати задокументовані операції та повідомляти іменовані факти. Стан workflow визначається цими контрактами, а не HTML, розбором журналів чи припущенням про відповідність поведінки SDK команді CLI.

Ця сторінка визначає форму контракту, яку мають зберігати майбутні інструменти MCP, локальні агенти, скрипти й SDK.

Шари контракту

Шар	Стабільний інтерфейс	Вимога контракту
Отримання документації	Канонічні llms.txt і llms-full.txt відповідають стабільній документації 2.0. llms-2.0.txt і llms-full-2.0.txt є закріпленими псевдонімами тієї самої лінійки.	Використовуйте канонічні URL для роботи з продуктом 2.0. Закріплюйте -1.x.txt, коли URL має називати архівну лінійку 1.x, або -2.0.txt, коли споживачу потрібна явна URL-адреса мажорної версії.
Локальне виявлення	/mcp/workflows list_workflows	Список дозволених MCP застосунку називає відкриті ключі workflow, потрібні облікові дані, очікувані аргументи та придатність до smoke-тестів.
Операції workflow	MCP start_workflow, get_workflow_result, get_workflow_history, diagnose_workflow, repair_workflow, JSON-команди dw, клієнти SDK	Кожен клієнт повідомляє ID workflow, ID run, простір імен, чергу завдань, статус команди, класифікацію першопричини, спосіб усунення та іменовані поля помилок без зчитування UI.
Діагностика Server	/api/cluster/info, dw server:info --output=json, dw doctor --output=json, dw debug workflow --output=json	Факти сумісності, протоколів, черг завдань, worker і застряглих run машиночитані й обмежені.
Стійкі докази	Деталі обраного run та експорт історії Waterline	Replay, очікування, timer, лінія походження, джерело проєкції, перевірки цілісності, стійкі помилки й доступні дії оператора походять із типізованого стану.
Міжмовний паритет	Фікстури запитів CLI/Python і тести SDK	Спільні операції площини керування зберігають узгоджену форму запитів між мовами.

Кожен шар має бути придатним до окремого використання. Разом вони дають агенту достатньо контексту для невеликої зміни, її перевірки та пояснення результату.

Проєктування інструментів MCP

Нові інструменти MCP мають безпосередньо надавати поняття Durable Workflow:

• Використовуйте терміни продукту: workflow, run, черга завдань, розклад, історія, помилка, worker, простір імен і сумісність.
• Повертайте стабільні ідентифікатори й іменовані поля статусу, а не лише текстові підсумки.
• Для діагностичних інструментів повертайте об’єкти root_cause, remediation і next_actions, щоб агенти обирали наступну команду без розбору природної мови.
• Надавайте обмежені масиви й перегляди історії, помилок та payload, щоб клієнт перевіряв їх без завантаження необмеженого трасування.
• Розділяйте виявлення й зміну. Клієнт має з’ясувати, що існує та які облікові дані потрібні, перед запуском чи командою workflow.
• Робіть зміни явними й структурованими. Для локальних workflow прикладів repair_workflow є основною зміною відновлення. Він повертає конверт durable-workflow.v2.safe-mutation, навіть коли відновлення відхилене або не потрібне.
• Явно позначайте smoke-workflow без облікових даних, щоб агенти перевіряли локальне підключення без звернення до зовнішніх служб.
• Ніколи не включайте значення секретів, імена хостів конкретних клієнтів або облікові дані окремих записів в описи чи метадані результатів.

Endpoint /mcp/workflows sample-app є еталонним локальним інтерфейсом workflow. Майбутні сервери MCP конкретних проєктів мають дотримуватися того самого підходу: конфігурація володіє списком дозволених workflow, інструменти працюють лише з ними, а результати посилаються на стійкі факти workflow, які людина відтворить через dw, Waterline або SDK.

Паритет команд і SDK

Автоматизація має переходити між клієнтами без зміни семантики:

Сімейство операцій	Потрібна ознака паритету
start, signal, update, query, repair, cancel, terminate, archive	Тіла запитів CLI та SDK відповідають задокументованій формі площини керування.
history, describe, list, result	Відповіді зберігають стабільні ідентифікатори, назви статусів, часові позначки й поля помилок.
Черги завдань і worker	Місткість, оренди, слоти, сумісність та ID worker залишаються структурованими фактами.
Зовнішнє виконання	Конверти входу й результатів залишаються незалежними від мови та містять іменовані результати мосту.

Додаючи команду CLI, метод SDK або інструмент MCP для дії площини керування, обирайте спільну фікстуру або задокументований приклад JSON, за яким інший клієнт може виконати перевірку. Зручні для людей таблиці можуть існувати, але контракт автоматизації — JSON або JSONL.

Форма діагностичного звіту

Коли інструмент пояснює невдалий або застряглий run, звіт має містити:

• версію документації та використану сторінку;
• викликану команду, метод SDK або інструмент MCP;
• ID workflow, ID run, простір імен і чергу завдань;
• поточний статус і останній опис стійкої помилки;
• назви недавніх типізованих подій історії;
• незавершені очікування, timer, завдання чи оренди зовнішніх activity;
• доступні факти сумісності worker і черги завдань;
• іменований код завершення, статус HTTP, помилку перевірки або причину блокування;
• машиночитані root_cause.category і remediation.classification;
• чи була безпечна зміна відновлення дозволена, застосована, відхилена або не потрібна.

Ця форма робить звіти переносимими між локальними Laravel-застосунками, окремими розгортаннями Server, worker Python і майбутніми SDK.

Першопричина й усунення

Підтримуваний schema id першопричини — durable-workflow.v2.agent-root-cause. Діагностичні інструменти мають містити:

• category, наприклад activity_failure, workflow_failure, task_repair_attention, waiting_for_signal, history_growth_attention, in_progress або none;
• source.kind і source.id;
• retryable, severity і actionable.

Підтримуваний schema id усунення — durable-workflow.v2.agent-remediation. Він містить classification, summary, automatic_repair.tool, automatic_repair.allowed і next_actions. repair_workflow є підтримуваним локальним інтерфейсом відновлення MCP. За відсутності MCP його замінюють задокументований контракт JSON CLI dw та маршрути площини керування HTTP Server:

dw debug workflow <workflow-id> --output=json
dw workflow:history <workflow-id> <run-id> --output=json
dw workflow:repair <workflow-id> --output=json
dw system:repair-status --output=json
dw system:repair-pass --output=json

Ці команди є підтримуваним контрактом без MCP для перегляду, безпечних змін, діагностики й автоматизації відновлення.

Правила для агентів

Агенти можуть автоматизувати рутину, зберігаючи стійку модель:

• Оркестрація workflow залишається детермінованою.
• Ввід/вивід, випадковість, зовнішні виклики API та облікові дані розміщуються в activity або зовнішніх обробниках.
• Для керування workflow використовуються signal, update, query, розклади, timer і потоки повідомлень замість довільних таблиць стану.
• Експорт історії Waterline є доказом, а не API зміни.
• Списки маршрутів, внутрішні дані бази й рядки моделей конкретного фреймворку є деталями реалізації, якщо публічна документація явно не визначає їх як контракт.

Інваріант залишається зрозумілим людині: workflow записують стійкі рішення, activity виконують роботу, що може помилитися, а replay має пояснювати, що сталося. Контракт інструментів надає агентам стабільні інтерфейси для решти.

Пов’язані сторінки

• Розробка за допомогою AI
• Операційний цикл агента
• Інтерфейс workflow MCP
• Можливості клієнтів і worker
• Довідник HTTP API Server
• Моніторинг