Návrh CLI pre AI agentov: JSON, návratové kódy a čakanie

CLI pre AI agentov nie je len nástroj príkazového riadka pre ľudí, ktorý sa náhodou dá volať z modelu. Ide o operačný protokol. Agent potrebuje deterministické vstupy, štruktúrované výstupy, zmysluplné návratové kódy, stabilné kategórie chýb a spôsob, ako čakať, kým asynchrónna infraštruktúra dosiahne konečný stav.

Bez takejto zmluvy musí agent odhadovať úspech z textu, napríklad „nasadenie sa začalo“. Takýto odhad je nebezpečný, pretože prijatá požiadavka môže neskôr zlyhať počas buildu, kontrol stavu, spúšťania kontajnera alebo prepnutia prevádzky.

Prečo je nebezpečné odhadovať úspech nasadenia?

Väčšina infraštruktúrnych operácií je asynchrónna. API môže prijať nasadenie a vrátiť ID za niekoľko milisekúnd, zatiaľ čo samotný build trvá niekoľko minút. Ak agent oznámi úspech už pri prijatí požiadavky, každý ďalší krok bude založený na nesprávnom predpoklade.

Zvážte tento rozdiel:

Udalosť	Čo dokazuje	Čo nedokazuje
Požiadavka prijatá	Platforma požiadavke porozumela	Kód sa zostavil
Build dokončený	Vytvoril sa image alebo artefakt	Aplikácia sa spustila
Kontrola stavu úspešná	Nová inštancia odpovedala podľa požiadaviek	Obchodné toky fungujú
Prevádzka prepnutá	Release sa stal aktívnym	Zostane v zdravom stave
Sledovanie dostupnosti	Služba zostáva dostupná	Každá funkcia je správna

Človek si tento rozdiel môže všimnúť v dashboarde. Agent pracujúci s textom ho však potrebuje mať zakódovaný v rozhraní.

Zmluva príkazov Dockup oddeľuje zaradenie do frontu od dokončenia. Deploy bez --wait sa vráti okamžite s hodnotou waited:false; deploy s --wait blokuje, kým neskončí úspechom, chybou alebo timeoutom:

dockup deploy production/api --wait --json

Predvolený timeout je 900 sekúnd. Príkaz skončí s kódom 0 až po úspešnom konečnom stave. Ak výsledkom nie je úspech, skončí s nenulovým kódom deploy_failed alebo deploy_timeout.

Čo poskytuje AI agentovi CLI so štruktúrovaným JSON?

Štruktúrovaný JSON nahrádza interpretáciu textu pomenovanými poľami. Agent môže priamo nájsť status, deploymentId, target alebo code namiesto toho, aby sa spoliehal na interpunkciu, farby, šírku stĺpcov alebo formulácie.

Úspešný výsledok možno spracovať ako dáta:

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

Chyba používa rovnaký transportný tvar:

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

Dôležitým pravidlom návrhu je, že JSON sa zapisuje na stdout, zatiaľ čo upozornenia, ktoré nesmú narušiť parsovanie, idú na stderr. Logy v režime follow používajú NDJSON — jeden JSON objekt na riadok — takže volajúci môže stream spracúvať priebežne bez čakania na jedno obrovské pole.

Dockup používa --json naprieč celým rozhraním príkazov. Pri 135 príkazoch by bolo vyžadovanie toho, aby si agent pamätal príznaky, krehké. Referencia CLI a pribalená skill poskytujú inštrukcie k príkazom zosúladené s konkrétnou verziou, podľa ktorých sa má agent riadiť.

Dôležitou vlastnosťou návrhu nie je dômyselné objavovanie príkazov. Podstatné je, že agent dostáva aktuálne a štruktúrované prevádzkové pokyny a nevymýšľa si príznak podľa starého promptu.

Ako majú skutočné návratové kódy riadiť automatizáciu nasadenia?

Návratový kód operačného systému je najprenosnejší signál úspechu dostupný shellovým skriptom, CI runnerom a coding agentom. Kód 0 znamená, že príkaz dosiahol definovaný výsledok. Nenulový kód znamená, že volajúci musí prejsť do vetvy obnovy, eskalácie alebo ukončenia.

Tento shellový fragment je zámerne jednoduchý:

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

Nehľadá v stdout slovo „success“. Nepredpokladá, že HTTP odpoveď 202 znamená pripravenosť produkcie. Definíciu úspechu prenecháva CLI a zlyhanie odovzdáva nadradenému procesu.

Skutočné návratové kódy sú rovnako dôležité pre jednorazové príkazy vo vnútri kontajnera. PRO príkaz exec od Dockup vracia stdout, stderr a skutočný návratový kód príkazu:

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

Agent tak dokáže rozlíšiť dokončenú migráciu od príkazu, ktorý sa iba spustil. Ide o základný princíp produkčných ochranných mechanizmov pre AI agentov.

Ako čakanie na konečný stav nahrádza krehké pollingové slučky?

Ručne napísané pollingové slučky prinášajú skryté rozhodnutia: ako často sa má stav kontrolovať, ktoré stavy sú konečné, ako dlho čakať, či má dočasná sieťová chyba resetovať časovač a čo robiť pri reštarte kontajnera.

Agent sa v týchto rozhodnutiach môže ľahko pomýliť, najmä ak nepozná kompletný stavový automat platformy. Sémantiku čakania by mala vlastniť platforma.

Dockup poskytuje dva užitočné vzory:

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

deploy --wait čaká explicitne. push po odoslaní a spustení release čaká predvolene; --no-wait túto funkciu vypína. Oba príkazy vracajú návratový kód zodpovedajúci konečnému výsledku.

Rovnaká myšlienka platí aj pre sledovanie logov:

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

Stream sa skončí, keď build dosiahne úspech alebo zlyhanie. Konečný NDJSON objekt označuje done:true a neúspešný build skončí s nenulovým kódom. Volajúci tak nepotrebuje druhú implementáciu pollingu.

Pre dostupnosť aplikácie po nasadení vracia príkaz uptime od Dockup kontroly na úrovni minút, priemerný čas odpovede a p95:

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

Čakanie a monitorovanie sú odlišné koncepty. --wait odpovedá na otázku, či toto nasadenie dosiahlo konečný výsledok; uptime ukazuje, ako sa spustená služba správala v čase.

Ktorým kódom chýb by mal agent rozumieť?

Stabilné kategórie chýb umožňujú agentovi vykonať obmedzenú akciu bez interpretácie každej možnej správy. Dockup poskytuje napríklad tieto kódy:

Kód chyby	Význam	Bezpečná reakcia agenta
not_logged_in	Neexistuje použiteľný token	Zastaviť sa a vyžiadať autentifikáciu
not_linked	Pre push neexistuje cieľ .dockup	Nájsť cieľ alebo ho odovzdať
no_target	Službu nebolo možné identifikovať	Spustiť services --json
needs_confirm	Deštruktívna akcia nemá schválenie	Požiadať človeka
deploy_trigger_failed	Nasadenie sa nepodarilo spustiť	Oznámiť chybu API
deploy_failed	Build alebo nasadenie zlyhalo	Prečítať build logy
deploy_timeout	Po uplynutí limitu čakania stále prebieha	Oznámiť neistotu alebo vedome predĺžiť čakanie

Správa o chybe zostáva užitočným kontextom, ale prvú vetvu riadi kód. Automatizácia je tak odolná voči presnejšiemu zneniu alebo lokalizácii.

Súčasťou protokolu je aj potvrdzovanie. Deštruktívny príkaz by nemal potichu pokračovať len preto, že volajúci nie je interaktívny. Dockup takéto operácie bez --yes odmietne a vráti needs_confirm. Autonómny agent tak uvidí otázku, nie prekážku, ktorú treba obísť.

Bezpečnostný model je podrobnejšie opísaný v článku bezpečnostné osvedčené postupy.

Aká je minimálna zmluva pre CLI pripravené na produkciu?

CLI pre AI agentov pripravené na produkciu by malo spĺňať malú, ale prísnu zmluvu:

1. Každá operácia čítania aj zápisu má strojovo čitateľný výstup.
2. Zlyhanie vytvorí nenulový návratový kód procesu.
3. Asynchrónne mutácie môžu čakať na zdokumentovaný konečný stav.
4. Príkazy na čítanie nikdy nevracajú tajné hodnoty.
5. Deštruktívne akcie vyžadujú explicitné potvrdenie.
6. Chyby majú stabilné kódy vhodné na vetvenie.
7. Balík CLI a inštrukcie pre agenta zostávajú zosúladené s verziou.
8. Mutácie sa zaznamenávajú do auditnej stopy.

Skill od Dockup premieňa tieto pravidlá na predvolené správanie pre Claude Code a Codex. Agentovi prikazuje používať JSON, autentifikovať sa pomocou DOCKUP_TOKEN, vyhľadávať presné ciele, nasadzovať s --wait, chrániť prihlasovacie údaje a zastaviť sa pri needs_confirm.

Porovnajte tento model so širšími konceptmi v článku agent skills vs MCP. Skill poskytuje prevádzkové znalosti; CLI zostáva spustiteľným rozhraním, ktorého stav ukončenia a výstup definujú skutočný stav.

Testovacia matica pre príkaz určený agentovi

Pred vystavením akéhokoľvek infraštruktúrneho príkazu agentovi otestujte viac než len úspešný scenár:

Test	Očakávané správanie
Platná požiadavka	Výsledok vo formáte JSON a ukončenie s kódom 0
Neplatný token	Stabilný autentifikačný kód a nenulový návratový kód
Neznámy cieľ	Stabilný kód cieľa a žiadna mutácia
Dlho trvajúce nasadenie	Čaká na konečný stav alebo timeout
Neúspešné nasadenie	Nenulový návratový kód a diagnostikovateľné ID nasadenia
Chýbajúce schválenie deštruktívnej akcie	needs_confirm, žiadne vymazanie
Čítanie tajného údaja	Viditeľné metadáta kľúča, hodnota skrytá
Upozornenie počas JSON výstupu	Upozornenie na stderr, platný JSON na stdout

Táto matica je hodnotnejšia než uhladený progress spinner. Formátovanie pre ľudí možno pridať navrch; deterministickú zmluvu pre stroje už spätne nemožno vytvoriť.

Dokumentácia Dockup CLI ukazuje konkrétne príkazy, ktoré stoja za týmto modelom, zatiaľ čo článok vývoj s podporou AI vysvetľuje širší posun od manuálneho používania nástrojov k workflow riadenému agentmi.

Považujte observability za súčasť zmluvy príkazu

Mutácia určená agentovi by mala vracať identifikátory, ktoré umožnia neskoršie vyšetrovanie. Odpoveď nasadenia potrebuje cieľ a ID nasadenia; vytvorená databáza potrebuje stabilný slug; snapshot volume potrebuje svoje ID snapshotu. Bez týchto odkazov môže agent udalosť opísať, no nedokáže spoľahlivo vykonať kontrolu, opakovanie ani vrátenie operácie.

Auditná stopa zmluvu uzatvára. Štruktúrovaný výstup opisuje jedno vyvolanie, zatiaľ čo auditné záznamy prepájajú viacero vyvolaní v čase. Spolu umožňujú operátorom overiť, či agent pracoval so zamýšľaným zdrojom a či neskorší príkaz na obnovu odkazoval na tú istú produkčnú udalosť.

Udržujte rozhranie jednoduché

Spoľahlivé CLI pre AI agentov by malo byť predvídateľné pri úspechu, zlyhaní, timeoute aj opakovaní.

Záverečný test rozhrania

CLI pre AI agentov musí zlyhanie oznámiť pravdivo.

Uveďte workflow do produkcie

Najprv otestujte zmluvu zo shellu: pred delegovaním prístupu k produkcii overte parsovanie JSON, úspešné ukončenie, vynútené zlyhanie, timeout a zablokovanú deštruktívnu operáciu.

npm install -g dockup-cli
dockup skill install

Prvý príkaz nainštaluje CLI. Druhý nainštaluje zodpovedajúcu skill Dockup pre Claude Code a Codex. Začnite bezplatne na app.dockup.ai.

Často kladené otázky

Čo robí CLI vhodným pre AI agentov?

Potrebuje štruktúrovaný výstup, skutočné návratové kódy, čakanie na konečný stav, stabilné kódy chýb, maskovanie tajných údajov a explicitné potvrdenie deštruktívnych operácií.

Prečo je JSON pre agentov lepší než výstup CLI formátovaný pre ľudí?

JSON poskytuje stabilné názvy a typy polí. Agent nemusí odvodzovať význam z farieb, tabuliek, interpunkcie ani meniaceho sa textu.

Prečo prijatá požiadavka na nasadenie neznamená úspech?

Prijatie dokazuje iba to, že platforma zaradila operáciu do frontu. Neskorší build, spustenie, kontrola stavu aj prepnutie prevádzky môžu stále zlyhať.

Aký je predvolený timeout čakania pri nasadení v Dockup?

Predvolený timeout pre dockup deploy --wait je 900 sekúnd a možno ho zmeniť zdokumentovanou voľbou --timeout.

Ako má agent reagovať na needs_confirm?

Mal by sa zastaviť a vyžiadať si explicitné schválenie. Tento kód znamená, že požadovaná akcia je deštruktívna a zámerne sa nevykonala.