Návrh CLI pro AI agenty: JSON, návratové kódy a čekání

CLI pro AI agenty není jen nástroj příkazového řádku pro lidi, který lze náhodou volat z modelu. Jde o operational protocol. Agent potřebuje deterministické vstupy, strukturované výstupy, smysluplné návratové kódy, stabilní kategorie chyb a možnost počkat, než asynchronní infrastruktura dosáhne finálního stavu.

Bez této smlouvy musí agent odvozovat úspěch z textu typu „nasazení spuštěno“. Takový odhad je nebezpečný, protože přijatý požadavek může později selhat při buildu, health checks, spuštění kontejneru nebo přepnutí provozu.

Proč je nebezpečné odhadovat úspěch nasazení?

Většina infrastrukturních operací je asynchronní. API může přijmout nasazení a vrátit ID během několika milisekund, zatímco samotný build trvá několik minut. Pokud agent ohlásí úspěch už při přijetí požadavku, každý další krok vychází z nesprávného předpokladu.

Zvažte tento rozdíl:

Událost	Co dokazuje	Co nedokazuje
Požadavek přijat	Platforma požadavku porozuměla	Kód se sestavil
Build dokončen	Byl vytvořen image nebo artifact	Aplikace se spustila
Health gate prošel	Nová instance odpověděla podle očekávání	Business flows fungují
Provoz přepnut	Release se stal aktivním	Zůstane ve zdravém stavu
Pozorování uptime	Služba zůstává dostupná	Každá funkce funguje správně

Člověk si rozdílu může všimnout v dashboardu. Agent pracující s textem ho ale potřebuje mít zakódovaný v rozhraní.

Smlouva příkazů Dockup odděluje zařazení do fronty od dokončení. Deploy bez --wait se vrátí okamžitě s hodnotou waited:false; deploy s --wait blokuje, dokud neskončí úspěchem, chybou nebo timeoutem:

dockup deploy production/api --wait --json

Výchozí timeout je 900 sekund. Příkaz skončí s kódem 0 pouze po úspěšném terminálním stavu. Pokud výsledek není úspěšný, skončí s nenulovým kódem a chybou deploy_failed nebo deploy_timeout.

Co poskytuje AI agentovi strukturované JSON CLI?

Strukturovaný JSON nahrazuje interpretaci prózy pojmenovanými poli. Agent může přímo najít status, deploymentId, target nebo code, místo aby závisel na interpunkci, barvě, šířce sloupců nebo formulaci.

Úspěšný výsledek lze zpracovat jako data:

{
  "ok": true,
  "target": "production/api",
  "deploymentId": "dep_123",
  "waited": true,
  "status": "success",
  "durationMs": 142381,
  "url": "https://api.dockup.tech"
}

Chyba používá stejný transportní tvar:

{
  "ok": false,
  "error": "Deployment failed",
  "code": "deploy_failed"
}

Důležitým pravidlem návrhu je, že JSON se zapisuje na stdout, zatímco warningy, které nesmějí narušit parsování, se posílají na stderr. Logy v režimu follow používají NDJSON – jeden JSON objekt na řádek – takže volající může stream zpracovávat průběžně, aniž by čekal na jedno obrovské pole.

Dockup používá --json napříč celým rozhraním příkazů. U 135 příkazů by bylo křehké vyžadovat po agentovi, aby si přepínače pamatoval. Reference CLI a přibalená skill poskytují instrukce k příkazům odpovídající aktuální verzi, kterými se má agent řídit.

Důležitou vlastností návrhu není chytré objevování. Podstatné je, že agent dostává aktuální a strukturované provozní pokyny a nevymýšlí si přepínač podle starého promptu.

Jak mají skutečné návratové kódy řídit automatizaci nasazení?

Návratový kód operačního systému je nejpřenosnější dostupný signál úspěchu pro shell skripty, CI runners a coding agenty. Kód 0 znamená, že příkaz dosáhl definovaného výsledku. Nenulový kód znamená, že volající musí přejít k recovery, eskalaci nebo ukončení.

Tento fragment shellu je záměrně nezajímavý:

if dockup deploy production/api --wait --json > result.json; then
  echo "deployment reached success"
else
  dockup logs production/api --build --json
  exit 1
fi

Nehledá ve stdout slovo „success“. Nepředpokládá, že HTTP 202 znamená připravenou produkci. Definici úspěchu přenechává CLI a předává chybu nadřazenému procesu.

Skutečné návratové kódy jsou stejně důležité u jednorázových příkazů uvnitř kontejneru. PRO příkaz exec od Dockup vrací stdout, stderr a skutečný návratový kód příkazu:

dockup exec "npm run migrate" \
  -s production/api \
  --json

Agent tak dokáže rozlišit dokončenou migraci od příkazu, který se pouze spustil. Jde o základní princip ochranných mechanismů pro AI agenty v produkci.

Jak čekání na terminální stav nahrazuje křehký polling?

Ručně psané polling loops zavádějí skrytá rozhodnutí o policy: jak často dotazovat stav, které stavy jsou terminální, jak dlouho čekat, zda má transientní síťová chyba resetovat časovač a co dělat při restartu kontejneru.

Agent tato rozhodnutí pravděpodobně nastaví nesprávně, zejména pokud nezná kompletní state machine platformy. Sémantiku čekání by měla vlastnit platforma.

Dockup poskytuje dva užitečné vzory:

dockup deploy production/api --wait --timeout 1800 --json
dockup push --json

deploy --wait čeká explicitně. push po pushnutí a spuštění release čeká ve výchozím nastavení; --no-wait toto čekání vypíná. Oba příkazy vracejí návratový kód odpovídající terminálnímu výsledku.

Stejnou myšlenku následuje i sledování logů:

dockup logs production/api --build -f --json

Stream skončí, jakmile build dosáhne úspěchu nebo chyby. Finální objekt NDJSON označí done:true a neúspěšný build skončí s nenulovým kódem. Volající nepotřebuje druhou implementaci pollingu.

Pro ověření dostupnosti aplikace po nasazení vrací uptime příkaz Dockup kontroly po minutách, průměrnou dobu odezvy a p95:

dockup uptime production/api --hours 24 --json

Čekání a monitoring jsou dva odlišné koncepty. --wait odpovídá na otázku, zda toto nasazení dosáhlo terminálního výsledku; uptime ukazuje, jak se spuštěná služba v průběhu času chovala.

Které chybové kódy by měl agent znát?

Stabilní kategorie chyb umožňují agentovi provést omezenou akci bez interpretace každé možné zprávy. Dockup poskytuje například tyto kódy:

Chybový kód	Význam	Bezpečná reakce agenta
not_logged_in	Neexistuje použitelný token	Zastavit a vyžádat autentizaci
not_linked	Pro push neexistuje cíl .dockup	Vyřešit cíl nebo ho předat explicitně
no_target	Službu se nepodařilo identifikovat	Spustit services --json
needs_confirm	Destruktivní akce nemá schválení	Požádat člověka
deploy_trigger_failed	Nasazení se nepodařilo spustit	Ohlásit chybu API
deploy_failed	Build nebo deploy skončil chybou	Načíst build logy
deploy_timeout	Po uplynutí limitu čekání stále probíhá	Ohlásit nejistotu nebo záměrně prodloužit čekání

Chybová zpráva zůstává užitečným kontextem, ale první větev řídí kód. Automatizace je tak odolná vůči přesnějším formulacím nebo lokalizaci.

Součástí protokolu je také potvrzování. Destruktivní příkaz by neměl tiše pokračovat jen proto, že volající není interaktivní. Dockup takové operace bez --yes odmítne a vrátí needs_confirm. Autonomní agent uvidí otázku, nikoli překážku, kterou by měl obejít.

Bezpečnostní model dále rozebíráme v článku osvědčené bezpečnostní postupy.

Jaká je minimální smlouva pro CLI připravené na produkci?

Produkčně připravené CLI pro AI agenty by mělo splňovat malou, ale přísnou smlouvu:

1. Každá operace čtení i zápisu má strojově čitelný výstup.
2. Chyba vede k nenulovému návratovému kódu procesu.
3. Asynchronní mutace mohou čekat na zdokumentovaný terminální stav.
4. Čtecí příkazy nikdy nevracejí hodnoty secretů.
5. Destruktivní akce vyžadují explicitní potvrzení.
6. Chyby mají stabilní kódy vhodné pro větvení.
7. Balíček CLI a instrukce pro agenta zůstávají sladěné podle verze.
8. Mutace se zaznamenávají do audit trailu.

Skill Dockup převádí tato pravidla na výchozí chování pro Claude Code a Codex. Agenta instruuje, aby používal JSON, autentizoval se pomocí DOCKUP_TOKEN, zjišťoval přesné cíle, nasazoval s --wait, chránil credentials a zastavil se při needs_confirm.

Tento model porovnejte s širšími koncepty v článku agent skills vs MCP. Skill poskytuje provozní znalosti; CLI zůstává spustitelným rozhraním, jehož návratový stav a výstup definují skutečnost.

Testovací matice příkazu určeného agentovi

Než infrastrukturu vystavíte agentovi, otestujte víc než jen happy path:

Test	Očekávané chování
Platný požadavek	JSON výsledek a návratový kód 0
Neplatný token	Stabilní auth kód a nenulový návratový kód
Neznámý cíl	Stabilní kód cíle a žádná mutace
Dlouho trvající deploy	Čeká na terminální stav nebo timeout
Neúspěšný deploy	Nenulový návratový kód a diagnostikovatelné ID nasazení
Chybějící schválení destruktivní akce	needs_confirm, žádné smazání
Čtení secretu	Metadata klíče viditelná, hodnota zamaskovaná
Warning během JSON výstupu	Warning na stderr, platný JSON na stdout

Tato matice je cennější než propracovaný progress spinner. Human formatting lze navrstvit; deterministickou machine contract už zpětně rekonstruovat nelze.

Dokumentace Dockup CLI ukazuje konkrétní příkazy tohoto modelu, zatímco článek vývoj s podporou AI vysvětluje širší posun od ručního používání nástrojů k workflow řízenému agentem.

Považujte observability za součást smlouvy příkazu

Mutace určená agentovi by měla vracet identifikátory, které umožní pozdější analýzu. Odpověď nasazení potřebuje cíl a ID nasazení; vytvořená databáze potřebuje stabilní slug; snapshot volume potřebuje své ID snapshotu. Bez těchto odkazů může agent událost popsat, ale nemůže spolehlivě provést kontrolu, opakování ani návrat změny.

Audit trail tuto smlouvu uzavírá. Strukturovaný výstup popisuje jedno vyvolání, zatímco auditní záznamy propojují více vyvolání v čase. Společně operátorům umožňují zjistit, zda agent pracoval se zamýšleným zdrojem a zda pozdější recovery příkaz odkazoval na stejnou produkční událost.

Udržujte rozhraní nezajímavé

Spolehlivé CLI pro AI agenty by mělo být předvídatelné při úspěchu, chybě, timeoutu i opakování.

Finální test rozhraní

CLI pro AI agenty musí selhávat pravdivě.

Uveďte workflow do produkce

Nejprve smlouvu otestujte ze shellu: před delegováním přístupu k produkci ověřte parsování JSON, úspěšný návratový kód, vynucenou chybu, timeout a zablokovanou destruktivní operaci.

npm install -g dockup-cli
dockup skill install

První příkaz nainstaluje CLI. Druhý nainstaluje odpovídající skill Dockup pro Claude Code a Codex. Začněte zdarma na app.dockup.ai.

FAQ

Co činí CLI vhodným pro AI agenty?

Potřebuje strukturovaný výstup, skutečné návratové kódy, čekání na terminální stav, stabilní chybové kódy, maskování secretů a explicitní potvrzení destruktivních operací.

Proč je JSON pro agenty lepší než výstup CLI formátovaný pro lidi?

JSON poskytuje stabilní názvy polí a typy. Agent nemusí odvozovat význam z barev, tabulek, interpunkce ani měnící se prózy.

Proč není přijatý požadavek na nasazení úspěchem?

Přijetí dokazuje pouze to, že platforma zařadila operaci do fronty. Následný build, spuštění, health gate i přepnutí provozu mohou stále selhat.

Jaký je výchozí timeout čekání při nasazení v Dockup?

Výchozí timeout pro dockup deploy --wait je 900 sekund a lze ho změnit pomocí zdokumentované volby --timeout.

Jak by měl agent reagovat na needs_confirm?

Měl by se zastavit a požádat o explicitní schválení. Tento kód znamená, že požadovaná akce je destruktivní a záměrně nebyla provedena.