Проєктування CLI для AI-агентів: JSON, коди завершення та очікування
Проєктування CLI для AI-агентів потребує структурованого JSON, реальних кодів завершення, очікування кінцевого стану, стабільних помилок і безпечного підтвердження для production-автоматизації.
CLI для AI-агентів — це не просто інструмент командного рядка для людей, який випадково можна викликати з моделі. Це операційний протокол. Агенту потрібні детерміновані вхідні дані, структуровані результати, змістовні коди завершення, стабільні категорії помилок і спосіб очікувати, доки асинхронна інфраструктура не досягне кінцевого стану.
Без такого контракту агент змушений визначати успіх за текстом на кшталт «розгортання розпочато». Це небезпечно, адже прийнятий запит може згодом завершитися помилкою під час збірки, перевірок працездатності, запуску контейнера або перемикання трафіку.
Чому небезпечно вважати розгортання успішним?
Більшість операцій з інфраструктурою є асинхронними. API може прийняти розгортання та повернути ID за мілісекунди, тоді як фактична збірка триватиме кілька хвилин. Якщо агент повідомляє про успіх одразу після прийняття запиту, кожен наступний крок ґрунтується на хибній передумові.
Порівняймо:
| Подія | Що вона підтверджує | Чого вона не підтверджує |
|---|---|---|
| Запит прийнято | Платформа зрозуміла запит | Код успішно зібрано |
| Збірку завершено | Створено image або артефакт | Застосунок запущено |
| Перевірку працездатності пройдено | Новий інстанс відповідає вимогам | Бізнес-сценарії працюють |
| Трафік перемкнено | Реліз став активним | Він залишатиметься працездатним |
| Спостереження за uptime | Сервіс залишається доступним | Кожна функція працює коректно |
Людина може помітити цю різницю на дашборді. Агент, який працює через текстовий інтерфейс, потребує її явного кодування в інтерфейсі.
Контракт команд Dockup розділяє постановку в чергу та завершення операції. Команда deploy без --wait повертається одразу з waited:false, а deploy із --wait блокується до успіху, помилки або тайм-ауту:
dockup deploy production/api --wait --json
Стандартний тайм-аут становить 900 секунд. Команда завершується з кодом 0 лише після успішного кінцевого стану. Якщо результатом не є успіх, вона завершується з ненульовим кодом і повертає deploy_failed або deploy_timeout.
Що структурований JSON CLI дає AI-агенту?
Структурований JSON замінює інтерпретацію тексту доступом до іменованих полів. Агент може безпосередньо знайти status, deploymentId, target або code, не покладаючись на пунктуацію, кольори, ширину стовпців чи формулювання.
Успішний результат можна обробляти як дані:
{
"ok": true,
"target": "production/api",
"deploymentId": "dep_123",
"waited": true,
"status": "success",
"durationMs": 142381,
"url": "https://api.dockup.tech"
}
Помилка використовує ту саму транспортну структуру:
{
"ok": false,
"error": "Deployment failed",
"code": "deploy_failed"
}
Важливе правило проєктування: JSON записується в stdout, а попередження, які не мають пошкоджувати парсинг, — у stderr. Логи в режимі follow використовують NDJSON — один JSON-об’єкт у кожному рядку, — щоб викликач міг обробляти потік поступово, не очікуючи на одну величезну array.
Dockup застосовує --json до всього набору команд. Маючи 135 команд, було б ненадійно вимагати від агента запам’ятовувати прапорці. Довідник CLI та упакований skill містять узгоджені з версією інструкції щодо команд, яких має дотримуватися агент.
Важлива властивість такого підходу — не кмітливе виявлення можливостей. Важливо, що агент отримує актуальні структуровані операційні інструкції та не вигадує прапорець зі старого prompt.
Як реальні коди завершення керують автоматизацією розгортання?
Код завершення операційної системи — це найпереносиміший доступний сигнал успіху для shell-скриптів, CI-раннерів і coding agent. Код 0 означає, що команда досягла визначеного результату. Ненульовий код означає, що викликач має перейти до відновлення, ескалації або завершення роботи.
Цей фрагмент shell навмисно простий:
if dockup deploy production/api --wait --json > result.json; then
echo "deployment reached success"
else
dockup logs production/api --build --json
exit 1
fi
Він не шукає слово “success” у stdout. Він не припускає, що відповідь HTTP 202 означає готовність production. Він делегує визначення успіху CLI та передає помилку батьківському процесу.
Реальні коди завершення так само важливі для одноразових команд усередині контейнера. Команда Dockup PRO exec повертає stdout, stderr і фактичний код завершення команди:
dockup exec "npm run migrate" \
-s production/api \
--json
Тож агент може відрізнити завершену міграцію від команди, яка лише запустилася. Це фундаментальний принцип захисних механізмів production для AI-агентів.
Як очікування кінцевого стану замінює крихкий polling?
Власноруч написані цикли polling приховують політичні рішення: як часто надсилати запити, які стани є кінцевими, скільки чекати, чи має тимчасова мережева помилка скидати таймер і що робити під час перезапуску контейнера.
Агент особливо легко помилиться в таких рішеннях, оскільки може не знати повної state machine платформи. Платформа має сама керувати семантикою очікування.
Dockup надає два корисні патерни:
dockup deploy production/api --wait --timeout 1800 --json
dockup push --json
deploy --wait явно очікує завершення. push за замовчуванням очікує після надсилання змін і запуску релізу; --no-wait вимикає це очікування. Обидві команди повертають код завершення, що відображає кінцевий результат.
Слідування за логами працює за тим самим принципом:
dockup logs production/api --build -f --json
Потік завершується, коли збірка досягає стану успіху або помилки. Фінальний об’єкт NDJSON позначає done:true, а збірка з помилкою завершується з ненульовим кодом. Викликачеві не потрібно реалізовувати ще одну версію polling.
Для перевірки доступності застосунку після розгортання команда Dockup uptime повертає похвилинні перевірки, середній час відповіді та p95:
dockup uptime production/api --hours 24 --json
Очікування та моніторинг — різні поняття. --wait відповідає на питання, чи досягло це розгортання кінцевого результату; uptime показує, як запущений сервіс поводився протягом певного часу.
Які коди помилок має розуміти агент?
Стабільні категорії помилок дають агенту змогу виконати обмежену дію, не інтерпретуючи кожне можливе повідомлення. Dockup надає такі коди:
| Код помилки | Значення | Безпечна реакція агента |
|---|---|---|
not_logged_in | Немає дійсного токена | Зупинитися та запросити автентифікацію |
not_linked | Для push немає цілі .dockup | Визначити ціль або передати її явно |
no_target | Не вдалося ідентифікувати сервіс | Виконати services --json |
needs_confirm | Для руйнівної дії немає підтвердження | Запитати людину |
deploy_trigger_failed | Не вдалося розпочати розгортання | Повідомити про помилку API |
deploy_failed | Збірка або розгортання завершилися помилкою | Переглянути логи збірки |
deploy_timeout | Операція все ще виконується після завершення ліміту очікування | Повідомити про невизначеність або свідомо збільшити ліміт |
Повідомлення про помилку залишається корисним контекстом, але саме код визначає першу гілку обробки. Завдяки цьому автоматизація не залежить від точнішого формулювання чи локалізації.
Підтвердження також є частиною протоколу. Руйнівна команда не має мовчки виконуватися лише тому, що викликач працює в неінтерактивному режимі. Dockup відхиляє такі операції без --yes і повертає needs_confirm. Автономний агент бачить запитання, а не перешкоду, яку потрібно обійти.
Модель безпеки докладніше розглянуто в матеріалі найкращі практики безпеки.
Який мінімальний контракт потрібен CLI для production?
Готовий до production CLI для AI-агентів має відповідати невеликому, але суворому контракту:
- Кожна операція читання та запису має машиночитаний вивід.
- Помилка призводить до ненульового коду завершення процесу.
- Асинхронні зміни можуть очікувати документований кінцевий стан.
- Значення секретів ніколи не повертаються командами читання.
- Руйнівні дії потребують явного підтвердження.
- Помилки мають стабільні коди, придатні для розгалуження логіки.
- Пакет CLI та інструкції для агента залишаються узгодженими з версією.
- Зміни фіксуються в audit trail.
Skill Dockup перетворює ці правила на стандартну поведінку для Claude Code і Codex. Він інструктує агента використовувати JSON, автентифікуватися через DOCKUP_TOKEN, знаходити точні цілі, виконувати розгортання з --wait, захищати облікові дані та зупинятися на needs_confirm.
Порівняйте цю модель із ширшими концепціями в матеріалі skills для агентів проти MCP. Skill надає операційні знання, а CLI залишається виконуваним інтерфейсом, чиї статус завершення та вивід визначають істину.
Матриця тестування команди, орієнтованої на агента
Перш ніж відкривати будь-яку інфраструктурну команду для агента, перевірте не лише успішний сценарій:
| Тест | Очікувана поведінка |
|---|---|
| Дійсний запит | Результат у JSON і код завершення 0 |
| Недійсний токен | Стабільний код автентифікації та ненульовий код завершення |
| Невідома ціль | Стабільний код цілі та відсутність змін |
| Тривале розгортання | Очікування до кінцевого стану або тайм-ауту |
| Невдале розгортання | Ненульовий код завершення та ідентифікатор розгортання для діагностики |
| Відсутнє підтвердження руйнівної дії | needs_confirm, видалення не виконано |
| Читання секрету | Метадані ключа видимі, значення замасковане |
| Попередження під час виводу JSON | Попередження у stderr, коректний JSON у stdout |
Ця матриця цінніша за бездоганно оформлений progress spinner. Людське форматування можна додати поверх; детермінований машинний контракт неможливо відновити постфактум.
Документація Dockup CLI показує конкретні команди, що реалізують цю модель, а матеріал розроблення за допомогою AI пояснює ширший перехід від ручного використання інструментів до workflow, керованих агентами.
Вважайте observability частиною контракту команди
Операція, орієнтована на агента, має повертати ідентифікатори, які дають змогу розслідувати події надалі. Відповідь на розгортання повинна містити ціль та ID розгортання; створена база даних — стабільний slug; snapshot volume — ID snapshot. Без цих посилань агент може описати подію, але не зможе надійно перевірити її, повторити спробу або скасувати результат.
Audit trail завершує контракт. Структурований вивід пояснює один виклик, а записи аудиту пов’язують численні виклики в часі. Разом вони дають операторам змогу визначити, чи діяв агент із потрібним ресурсом і чи стосувалася подальша команда відновлення тієї самої production-події.
Інтерфейс має залишатися простим
Надійний CLI для AI-агентів має бути передбачуваним під час успіху, помилки, тайм-ауту та повторної спроби.
Фінальна перевірка інтерфейсу
CLI для AI-агентів має правдиво повідомляти про помилки.
Перенесіть workflow у production
Спочатку протестуйте контракт із shell: перевірте парсинг JSON, успішне завершення, примусову помилку, тайм-аут і заблоковану руйнівну операцію, перш ніж делегувати доступ до production.
npm install -g dockup-cli
dockup skill install
Перша команда встановлює CLI. Друга встановлює відповідний skill Dockup для Claude Code і Codex. Почніть безкоштовно на app.dockup.ai.
FAQ
Що робить CLI придатним для AI-агентів?
Йому потрібні структурований вивід, реальні коди завершення, очікування кінцевого стану, стабільні коди помилок, маскування секретів і явне підтвердження руйнівних операцій.
Чому JSON кращий за форматований для людей вивід CLI для агентів?
JSON надає стабільні назви полів і типи даних. Агенту не потрібно визначати значення за кольорами, таблицями, пунктуацією чи змінним текстом.
Чому прийнятий запит на розгортання не означає успіх?
Прийняття лише підтверджує, що платформа поставила операцію в чергу. Подальші збірка, запуск, перевірка працездатності та перемикання трафіку все ще можуть завершитися помилкою.
Який стандартний тайм-аут очікування розгортання Dockup?
Стандартний тайм-аут для dockup deploy --wait становить 900 секунд. Його можна змінити за допомогою документованої опції --timeout.
Як агент має реагувати на needs_confirm?
Він має зупинитися та запросити явне підтвердження. Цей код означає, що запитана дія є руйнівною і навмисно не була виконана.