Designul unui CLI pentru agenți AI: JSON, coduri de ieșire și așteptare

Un CLI pentru agenți AI nu este doar un instrument de linie de comandă destinat oamenilor, care poate fi apelat și de un model. Este un protocol operațional. Agentul are nevoie de inputuri deterministe, rezultate structurate, coduri de ieșire relevante, categorii stabile de erori și o modalitate de a aștepta până când infrastructura asincronă ajunge într-o stare finală.

Fără acest contract, agentul este obligat să deducă succesul din formulări precum „deploymentul a început”. Această deducție este periculoasă, deoarece o solicitare acceptată poate eșua ulterior în timpul buildului, al verificărilor de sănătate, al pornirii containerului sau al comutării traficului.

De ce este periculoasă presupunerea succesului unui deployment?

Majoritatea operațiunilor de infrastructură sunt asincrone. Un API poate accepta un deployment și poate returna un ID în câteva milisecunde, în timp ce buildul propriu-zis durează câteva minute. Dacă un agent raportează succesul în momentul acceptării, fiecare pas ulterior se bazează pe o premisă falsă.

Să comparăm diferențele:

Eveniment	Ce demonstrează	Ce nu demonstrează
Solicitare acceptată	Platforma a înțeles solicitarea	Codul a fost compilat
Build finalizat	A fost creată o imagine sau un artifact	Aplicația a pornit
Verificarea de sănătate trecută	Noua instanță a răspuns conform cerințelor	Fluxurile de business funcționează
Trafic comutat	Release-ul a devenit activ	Va rămâne sănătos
Observarea disponibilității	Serviciul rămâne accesibil	Toate funcționalitățile sunt corecte

Un om poate observa diferența într-un dashboard. Un agent care operează prin text are nevoie ca aceasta să fie codificată în interfață.

Contractul de comenzi Dockup separă punerea în coadă de finalizare. Un deploy fără --wait revine imediat cu waited:false; un deploy cu --wait blochează execuția până la succes, eșec sau timeout:

dockup deploy production/api --wait --json

Timeoutul implicit este de 900 de secunde. Comanda se încheie cu 0 doar după atingerea unei stări terminale de succes. Se încheie cu o valoare diferită de zero și deploy_failed sau deploy_timeout atunci când rezultatul nu este unul de succes.

Ce oferă unui agent AI un CLI cu JSON structurat?

JSON-ul structurat înlocuiește interpretarea prozei cu câmpuri denumite. Agentul poate accesa direct status, deploymentId, target sau code, fără să depindă de punctuație, culori, lățimea coloanelor sau formulări.

Un rezultat de succes poate fi procesat ca date:

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

Un eșec folosește aceeași structură de transport:

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

Regula importantă de design este ca JSON-ul să fie scris în stdout, iar avertismentele care nu trebuie să corupă procesarea să fie trimise în stderr. Logurile în modul follow folosesc NDJSON—câte un obiect JSON pe linie—astfel încât apelantul să poată procesa incremental fluxul, fără să aștepte un singur array uriaș.

Dockup aplică --json întregii suprafețe de comenzi. Cu 135 de comenzi, ar fi fragil să i se ceară unui agent să deducă flagurile din memorie. Referința CLI și skill-ul inclus oferă instrucțiuni pentru comenzi aliniate la versiunea curentă, pe care agentul trebuie să le urmeze.

Proprietatea importantă de design nu este descoperirea ingenioasă. Este faptul că agentul primește îndrumări operaționale actuale și structurate și nu inventează un flag pe baza unui prompt vechi.

Cum ar trebui codurile reale de ieșire să controleze automatizarea deploymentului?

Codul de ieșire al sistemului de operare este cel mai portabil semnal de succes disponibil pentru scripturi shell, runner-e CI și agenți de coding. Ieșirea 0 înseamnă că acea comandă și-a atins rezultatul definit. O valoare diferită de zero înseamnă că apelantul trebuie să aleagă între recuperare, escaladare sau terminare.

Acest fragment shell este intenționat lipsit de artificii:

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

Nu caută cuvântul „success” în stdout. Nu presupune că un răspuns HTTP 202 înseamnă că producția este pregătită. Lasă CLI-ul să definească succesul și propagă eșecul către procesul părinte.

Codurile reale de ieșire sunt la fel de importante pentru comenzile one-shot executate într-un container. Comanda PRO exec de la Dockup returnează stdout, stderr și codul efectiv de ieșire al comenzii:

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

Prin urmare, un agent poate face diferența între o migrare finalizată și o comandă care doar a fost lansată. Acesta este un principiu fundamental al măsurilor de protecție pentru agenții AI în producție.

Cum înlocuiește așteptarea unei stări terminale mecanismele fragile de polling?

Buclele de polling scrise manual introduc decizii de politică ascunse: cât de des se face polling, care stări sunt terminale, cât timp trebuie așteptat, dacă o eroare de rețea temporară ar trebui să reseteze cronometrul și ce trebuie făcut atunci când un container repornește.

Un agent este cu atât mai predispus să ia decizii greșite, deoarece este posibil să nu cunoască întreaga mașină de stări a platformei. Platforma ar trebui să dețină semantica așteptării.

Dockup oferă două patternuri utile:

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

deploy --wait așteaptă explicit. push așteaptă implicit după efectuarea pushului și declanșarea release-ului; --no-wait dezactivează această așteptare. Ambele returnează un cod de ieșire care reflectă rezultatul terminal.

Urmărirea logurilor urmează aceeași idee:

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

Fluxul se încheie atunci când buildul ajunge la succes sau eșec. Un obiect NDJSON final marchează done:true, iar un build eșuat se încheie cu o valoare diferită de zero. Apelantul nu trebuie să implementeze o a doua soluție de polling.

Pentru disponibilitatea aplicației după deployment, comanda uptime de la Dockup returnează verificări la nivel de minut, timpul mediu de răspuns și p95:

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

Așteptarea și monitorizarea sunt concepte separate. --wait răspunde la întrebarea dacă acest deployment a ajuns la un rezultat terminal; uptime arată cum s-a comportat serviciul în execuție de-a lungul timpului.

Ce coduri de eroare ar trebui să înțeleagă un agent?

Categoriile stabile de erori îi permit unui agent să ia o măsură limitată, fără să interpreteze fiecare mesaj posibil. Dockup expune coduri precum:

Cod de eroare	Semnificație	Răspuns sigur al agentului
not_logged_in	Nu există un token utilizabil	Oprește execuția și solicită autentificarea
not_linked	Nu există o țintă .dockup pentru push	Rezolvă ținta sau transmite-o explicit
no_target	Serviciul nu a putut fi identificat	Rulează services --json
needs_confirm	Acțiunea distructivă nu are aprobare	Cere intervenția unui om
deploy_trigger_failed	Deploymentul nu a putut fi pornit	Raportează eroarea API-ului
deploy_failed	Buildul sau deploymentul a eșuat	Citește logurile buildului
deploy_timeout	Execuția continuă după limita de așteptare	Raportează incertitudinea sau extinde deliberat limita

Mesajul de eroare rămâne util ca informație contextuală, dar codul ghidează prima ramificație. Astfel, automatizarea rămâne rezilientă la formulări mai clare sau la localizare.

Confirmarea face și ea parte din protocol. O comandă distructivă nu ar trebui să continue în tăcere doar pentru că apelantul nu este interactiv. Dockup refuză astfel de operațiuni fără --yes și returnează needs_confirm. Un agent autonom vede o întrebare, nu o barieră pe care trebuie să o ocolească.

Modelul de siguranță este analizat mai în detaliu în cele mai bune practici de securitate.

Care este contractul minim pentru un CLI pregătit pentru producție?

Un CLI pentru agenți AI pregătit pentru producție ar trebui să respecte un contract restrâns, dar strict:

1. Fiecare operațiune de citire și scriere are rezultate care pot fi procesate automat.
2. Un eșec produce o valoare diferită de zero ca exit al procesului.
3. Mutațiile asincrone pot aștepta o stare terminală documentată.
4. Valorile secrete nu sunt returnate de comenzile de citire.
5. Acțiunile distructive necesită confirmare explicită.
6. Erorile au coduri stabile, potrivite pentru ramificare.
7. Pachetul CLI și instrucțiunile pentru agent rămân aliniate la aceeași versiune.
8. Mutațiile sunt înregistrate într-un audit trail.

Skill-ul Dockup transformă aceste reguli în comportament implicit pentru Claude Code și Codex. Îi indică agentului să folosească JSON, să se autentifice cu DOCKUP_TOKEN, să descopere ținte exacte, să facă deploy cu --wait, să protejeze credențialele și să se oprească la needs_confirm.

Compară acest model cu conceptele mai largi din skill-uri pentru agenți vs MCP. Un skill oferă cunoștințe operaționale; CLI-ul rămâne interfața executabilă ale cărei stare de ieșire și rezultate definesc adevărul.

O matrice de testare pentru o comandă destinată agenților

Înainte de a expune o comandă de infrastructură unui agent, testează mai mult decât happy path-ul:

Test	Comportament așteptat
Solicitare validă	Rezultat JSON și exit 0
Token invalid	Cod de autentificare stabil și exit diferit de zero
Țintă necunoscută	Cod de țintă stabil și nicio mutație
Deployment de lungă durată	Așteaptă până la starea terminală sau timeout
Deployment eșuat	Exit diferit de zero și deployment ID care permite diagnosticarea
Aprobare distructivă absentă	needs_confirm, fără ștergere
Citire de secrete	Metadatele cheii sunt vizibile, valoarea este mascată
Avertisment în timpul rezultatului JSON	Avertismentul ajunge în stderr, JSON valid în stdout

Această matrice este mai valoroasă decât un progress spinner bine finisat. Formatarea pentru oameni poate fi adăugată ulterior; un contract determinist pentru mașini nu mai poate fi reconstruit după fapt.

Documentația CLI Dockup prezintă comenzile concrete din spatele acestui model, iar dezvoltarea asistată de AI explică schimbarea mai amplă de la utilizarea manuală a instrumentelor la fluxuri de lucru coordonate de agenți.

Tratează observabilitatea ca parte a contractului comenzii

O mutație destinată unui agent ar trebui să returneze identificatori care fac posibilă investigarea ulterioară. Un răspuns de deployment are nevoie de țintă și deployment ID; o bază de date creată are nevoie de un slug stabil; un snapshot de volum are nevoie de snapshot ID. Fără aceste referințe, agentul poate descrie un eveniment, dar nu îl poate inspecta, reîncerca sau anula în mod fiabil.

Audit trail-ul completează contractul. Rezultatul structurat explică o singură invocare, în timp ce înregistrările de audit conectează mai multe invocări de-a lungul timpului. Împreună, acestea le permit operatorilor să răspundă dacă agentul a acționat asupra resursei vizate și dacă o comandă ulterioară de recuperare s-a referit la același eveniment din producție.

Păstrează interfața simplă

Un CLI pentru agenți AI de încredere ar trebui să fie previzibil în caz de succes, eșec, timeout și reîncercare.

Testul final al interfeței

CLI-ul pentru agenți AI trebuie să eșueze în mod fidel realității.

Du fluxul de lucru în producție

Testează mai întâi contractul dintr-un shell: verifică parsarea JSON-ului, un exit de succes, un eșec forțat, un timeout și o operațiune distructivă blocată înainte de a delega accesul la producție.

npm install -g dockup-cli
dockup skill install

Prima comandă instalează CLI-ul. A doua instalează skill-ul Dockup compatibil pentru Claude Code și Codex. Începe gratuit la app.dockup.ai.

Întrebări frecvente

Ce face un CLI potrivit pentru agenți AI?

Are nevoie de rezultate structurate, coduri reale de ieșire, așteptarea unei stări terminale, coduri stabile de eroare, mascarea secretelor și confirmare explicită pentru operațiunile distructive.

De ce este JSON mai bun decât rezultatele CLI formatate pentru oameni în cazul agenților?

JSON oferă nume și tipuri stabile pentru câmpuri. Agentul nu trebuie să deducă semnificația din culori, tabele, punctuație sau formulări schimbătoare.

De ce o solicitare de deployment acceptată nu înseamnă succes?

Acceptarea demonstrează doar că platforma a pus operațiunea în coadă. Buildul, pornirea, verificarea de sănătate și comutarea traficului pot eșua ulterior.

Care este timeoutul implicit de așteptare pentru deploymenturile Dockup?

Timeoutul implicit pentru dockup deploy --wait este de 900 de secunde și poate fi modificat folosind opțiunea documentată --timeout.

Cum ar trebui să reacționeze un agent la needs_confirm?

Ar trebui să se oprească și să solicite aprobare explicită. Codul indică faptul că acțiunea solicitată este distructivă și nu a fost executată intenționat.