AI Agent CLI-tervezés: JSON, kilépési kódok és várakozás

Egy AI agent CLI nem egyszerűen egy olyan emberi használatra szánt parancssori eszköz, amelyet véletlenül egy modell is meg tud hívni. Ez egy működési protokoll. Az ügynöknek determinisztikus bemenetekre, strukturált kimenetre, értelmezhető kilépési kódokra, stabil hibakategóriákra és arra van szüksége, hogy meg tudja várni, amíg az aszinkron infrastruktúra elér egy végső állapotot.

E szerződés nélkül az ügynök kénytelen olyan szövegekből kikövetkeztetni a sikert, mint például: „a deployment elindult”. Ez a következtetés veszélyes, mert egy elfogadott kérés később meghiúsulhat a build, a health checkek, a konténer indítása vagy a forgalom átirányítása során.

Miért veszélyes a deployment sikerét találgatni?

A legtöbb infrastruktúra-művelet aszinkron. Egy API ezredmásodpercek alatt elfogadhat egy deploymentet, és visszaadhat egy azonosítót, miközben maga a build több percig tart. Ha az ügynök már az elfogadás pillanatában sikert jelez, minden további lépés hamis előfeltevésre épül.

Vegyük szemügyre a különbséget:

Esemény	Mit bizonyít?	Mit nem bizonyít?
A kérés elfogadva	A platform megértette a kérést	Hogy a kód lefordult
A build elkészült	Létrejött egy image vagy artifact	Hogy az alkalmazás elindult
A health gate sikeres	Az új példány az elvárásoknak megfelelően válaszolt	Hogy az üzleti folyamatok működnek
A forgalom átirányítva	A release aktívvá vált	Hogy egészséges is marad
Uptime-megfigyelés	A szolgáltatás továbbra is elérhető	Hogy minden funkció helyesen működik

Egy ember észreveheti ezt a különbséget egy dashboardon. A szövegen keresztül működő ügynöknek azonban ezt az interfészben kell kódolva megkapnia.

A Dockup parancsszerződése különválasztja a sorba állítást a befejezéstől. A --wait nélküli deploy azonnal visszatér waited:false értékkel; a --wait kapcsolóval végrehajtott deploy sikerig, hibáig vagy timeoutig blokkol:

dockup deploy production/api --wait --json

Az alapértelmezett timeout 900 másodperc. A parancs csak sikeres terminálállapot után lép ki 0 kóddal. Ha az eredmény nem sikeres, nem nulla értékkel tér vissza, és deploy_failed vagy deploy_timeout kódot ad.

Mit ad egy strukturált JSON CLI egy AI-ügynöknek?

A strukturált JSON a próza értelmezését elnevezett mezőkkel váltja fel. Az ügynök közvetlenül megtalálhatja a status, deploymentId, target vagy code mezőt, ahelyett hogy írásjelekre, színekre, oszlopszélességre vagy megfogalmazásra támaszkodna.

A sikeres eredmény adatként dolgozható fel:

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

A hibák ugyanazt a transzportstruktúrát használják:

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

A legfontosabb tervezési szabály, hogy a JSON a stdoutra kerüljön, míg az értelmezést nem zavaró figyelmeztetések a stderrre menjenek. A follow mód logjai NDJSON-formátumot használnak — soronként egy JSON-objektumot —, így a hívó fokozatosan dolgozhatja fel a streamet anélkül, hogy egyetlen hatalmas tömbre kellene várnia.

A Dockup a --json kapcsolót a teljes parancsfelületén alkalmazza. 135 parancs mellett törékeny megoldás lenne, ha az ügynöknek memóriából kellene kitalálnia a kapcsolókat. A CLI-referencia és a csomagolt skill olyan, verzióhoz igazított parancsutasításokat biztosít, amelyeket az ügynöknek követnie kell.

A fontos tervezési szempont nem az intelligens felfedezés. Hanem az, hogy az ügynök aktuális, strukturált működési útmutatást kapjon, és ne találjon ki egy régi promptból származó kapcsolót.

Hogyan vezérelhetik a valódi kilépési kódok a deployment automatizálását?

Az operációs rendszer kilépési kódja a shell scriptek, CI-futtatók és coding agentek számára elérhető leginkább hordozható sikerjelzés. A 0-s kilépési kód azt jelenti, hogy a parancs elérte a meghatározott eredményt. A nem nulla kód azt jelzi, hogy a hívónak helyreállítást, eszkalációt vagy leállást kell választania.

Ez a shell-részlet szándékosan unalmas:

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

Nem keresi a „success” szót a stdouton. Nem feltételezi, hogy egy HTTP 202-es válasz azt jelenti, hogy a production készen áll. A siker meghatározását a CLI-re bízza, a hibát pedig továbbadja a szülőfolyamatnak.

A valódi kilépési kódok a konténeren belül futó egyszeri parancsok esetében is fontosak. A Dockup PRO exec parancsa visszaadja a stdoutot, a stderrt és a tényleges parancs-kilépési kódot:

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

Az ügynök így különbséget tud tenni egy befejezett migráció és egy olyan parancs között, amely csupán elindult. Ez az AI agent production guardrails egyik alapelve.

Hogyan váltja fel a terminálállapot megvárása a törékeny pollingot?

A kézzel írt polling loopok rejtett szabályozási döntéseket vezetnek be: milyen gyakran kell pollingolni, mely állapotok számítanak terminálisnak, meddig kell várni, egy átmeneti hálózati hiba újraindítsa-e az időzítőt, és mi történjen egy konténer újraindulásakor.

Ezeket a döntéseket különösen könnyű elrontania egy ügynöknek, mert nem biztos, hogy ismeri a platform teljes állapotgépét. A várakozás szemantikáját a platformnak kell kezelnie.

A Dockup két hasznos mintát biztosít:

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

A deploy --wait explicit módon vár. A push alapértelmezés szerint vár a push és a release elindítása után; a --no-wait kapcsolóval lehet kikapcsolni ezt a viselkedést. Mindkettő olyan kilépési kódot ad vissza, amely tükrözi a terminális eredményt.

A logok követése ugyanezt az elvet alkalmazza:

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

A stream akkor ér véget, amikor a build sikeres vagy sikertelen állapotba kerül. Egy végső NDJSON-objektum jelzi a done:true értéket, sikertelen build esetén pedig a parancs nem nulla kilépési kóddal tér vissza. A hívónak nincs szüksége egy második pollingimplementációra.

A deployment utáni alkalmazás-elérhetőséghez a Dockup uptime parancsa percszintű ellenőrzéseket, átlagos válaszidőt és p95 értéket ad vissza:

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

A várakozás és a monitoring két külön fogalom. A --wait arra ad választ, hogy ez a deployment elérte-e a terminális eredményt; az uptime pedig azt mutatja meg, hogyan viselkedett a futó szolgáltatás egy adott időszakban.

Mely hibakódokat kell az ügynöknek ismernie?

A stabil hibakategóriák lehetővé teszik, hogy az ügynök minden lehetséges üzenet értelmezése nélkül, korlátozott és kiszámítható műveletet hajtson végre. A Dockup többek között ilyen kódokat tesz elérhetővé:

Hibakód	Jelentés	Biztonságos ügynöki válasz
not_logged_in	Nincs használható token	Álljon le, és kérjen hitelesítést
not_linked	A push célpontjához nincs .dockup	Oldja fel a célpontot, vagy adja meg explicit módon
no_target	Nem sikerült azonosítani a szolgáltatást	Futtassa a services --json parancsot
needs_confirm	A destruktív művelethez nincs jóváhagyás	Kérdezzen meg egy embert
deploy_trigger_failed	Nem sikerült elindítani a deploymentet	Adja vissza az API hibáját
deploy_failed	A build vagy a deploy hibával zárult	Olvassa el a build logjait
deploy_timeout	A művelet a várakozási korlát elérésekor még futott	Jelezze a bizonytalanságot, vagy tudatosan hosszabbítsa meg a várakozást

A hibaüzenet továbbra is hasznos kontextust biztosít, de az első elágazást a kód vezérli. Így az automatizálás ellenálló marad az egyértelműbb megfogalmazással vagy a lokalizációval szemben.

A megerősítés szintén a protokoll része. Egy destruktív parancs nem hajtható végre csendben csak azért, mert a hívó nem interaktív. A Dockup --yes nélkül elutasítja ezeket a műveleteket, és needs_confirm kódot ad vissza. Az autonóm ügynök ilyenkor kérdést lát, nem pedig megkerülendő akadályt.

A biztonsági modellt részletesebben a security best practices mutatja be.

Mi a productionre kész CLI minimális szerződése?

Egy productionre kész AI agent CLI-nek egy kicsi, de szigorú szerződésnek kell megfelelnie:

1. Minden olvasási és írási művelet géppel olvasható kimenetet ad.
2. A hibák nem nulla folyamat-kilépési kódot eredményeznek.
3. Az aszinkron módosítások megvárhatják a dokumentált terminális állapotot.
4. Az olvasási parancsok soha nem adnak vissza titkos értékeket.
5. A destruktív műveletekhez explicit megerősítés szükséges.
6. A hibák stabil, elágazásokhoz használható kódokkal rendelkeznek.
7. A CLI-csomag és az ügynök utasításai verzióban összehangoltak maradnak.
8. A módosítások audit trailben kerülnek rögzítésre.

A Dockup skillje ezeket a szabályokat alapértelmezett működéssé alakítja a Claude Code és a Codex számára. Arra utasítja az ügynököt, hogy JSON-t használjon, a DOCKUP_TOKEN segítségével hitelesítsen, derítse fel a pontos célpontokat, --wait kapcsolóval deployoljon, védje a hitelesítő adatokat, és needs_confirm esetén álljon le.

Hasonlítsuk össze ezt a modellt az agent skills vs MCP tágabb fogalmaival. A skill működési tudást biztosít; a CLI marad a végrehajtható interfész, amelynek kilépési állapota és kimenete határozza meg az igazságot.

Tesztmátrix ügynökök által használt parancsokhoz

Mielőtt egy infrastruktúra-parancsot ügynök számára elérhetővé tennél, ne csak a sikeres esetet teszteld:

Teszt	Elvárt viselkedés
Érvényes kérés	JSON-eredmény és 0-s kilépési kód
Érvénytelen token	Stabil hitelesítési kód és nem nulla kilépési kód
Ismeretlen célpont	Stabil célpontkód és módosítás nélkül
Hosszan futó deploy	Várakozás a terminális állapotig vagy timeoutig
Sikertelen deploy	Nem nulla kilépési kód és diagnosztizálható deployment ID
Hiányzó destruktív jóváhagyás	needs_confirm, törlés nélkül
Titkos érték olvasása	A kulcs metaadata látható, az érték maszkolva
Figyelmeztetés JSON-kimenet közben	A figyelmeztetés a stderrre kerül, a stdout érvényes JSON marad

Ez a mátrix értékesebb, mint egy igényesen megformázott progress spinner. Az emberi formázás utólag ráépíthető; egy determinisztikus gépi szerződés azonban utólag nem rekonstruálható.

A Dockup CLI dokumentációja bemutatja a modell mögött álló konkrét parancsokat, míg az AI-alapú fejlesztés a manuális eszközhasználattól az ügynökök által vezérelt munkafolyamatok felé történő nagyobb elmozdulást magyarázza.

Kezeld a megfigyelhetőséget a parancsszerződés részeként

Egy ügynök által használt módosító műveletnek olyan azonosítókat kell visszaadnia, amelyek lehetővé teszik a későbbi vizsgálatot. Egy deployment válaszának tartalmaznia kell a célpontot és a deployment ID-t; egy létrehozott adatbázisnak stabil sluggal kell rendelkeznie; egy volume snapshotnak pedig a saját snapshot ID-ját kell visszaadnia. E hivatkozások nélkül az ügynök leírhat egy eseményt, de nem tudja megbízhatóan megvizsgálni, újrapróbálni vagy visszavonni azt.

Az audit trail teszi teljessé a szerződést. A strukturált kimenet egyetlen meghívásról ad magyarázatot, míg az auditrekordok időben összekapcsolják a több meghívást. Együtt lehetővé teszik az üzemeltetők számára annak megválaszolását, hogy az ügynök a kívánt erőforráson hajtotta-e végre a műveletet, illetve hogy egy későbbi helyreállítási parancs ugyanarra a productioneseményre hivatkozott-e.

Legyen az interfész unalmas

Egy megbízható AI agent CLI siker, hiba, timeout és újrapróbálás esetén is kiszámíthatóan viselkedik.

Végső interfészteszt

Az AI agent CLI-nek őszintén kell hibáznia.

Vidd productionbe a munkafolyamatot

Először shellből teszteld a szerződést: ellenőrizd a JSON feldolgozását, a sikeres kilépést, a kikényszerített hibát, a timeoutot és a blokkolt destruktív műveletet, mielőtt productionhozzáférést delegálnál.

npm install -g dockup-cli
dockup skill install

Az első parancs telepíti a CLI-t. A második telepíti a Claude Code és a Codex számára készült, megfelelő Dockup skillt. Kezdd el ingyen az app.dockup.ai oldalon.

GYIK

Mitől alkalmas egy CLI AI-ügynökök használatára?

Strukturált kimenetre, valódi kilépési kódokra, terminálállapot megvárására, stabil hibakódokra, titkos értékek maszkolására és a destruktív műveletek explicit megerősítésére van szüksége.

Miért jobb a JSON az emberi formázású CLI-kimenetnél az ügynökök számára?

A JSON stabil mezőneveket és típusokat biztosít. Az ügynöknek nem kell színekből, táblázatokból, írásjelekből vagy változó szövegezésből kikövetkeztetnie a jelentést.

Miért nem jelent sikert egy elfogadott deploymentkérés?

Az elfogadás csak azt bizonyítja, hogy a platform sorba állította a műveletet. A későbbi build, indítás, health gate és forgalom-átirányítás továbbra is meghiúsulhat.

Mennyi a Dockup deployment-várakozásának alapértelmezett timeoutja?

A dockup deploy --wait alapértelmezett timeoutja 900 másodperc, és a dokumentált --timeout kapcsolóval módosítható.

Hogyan reagáljon az ügynök a needs_confirm kódra?

Álljon le, és kérjen explicit jóváhagyást. A kód azt jelenti, hogy a kért művelet destruktív, ezért szándékosan nem lett végrehajtva.