Claude Code CLI ca runtime de agent: de ce nu am scris un framework custom

Când construiești un agent AI care trebuie să citească și scrie fișiere, să apeleze tools, să-și păstreze context între pași, opțiunea dominantă în 2025-2026 a fost: scrie un framework custom peste un SDK LLM. Mii de echipe au investit luni în această direcție. Noi am ales o cale alternativă: folosim Claude Code CLI ca subprocess al agentului nostru. Beneficiile s-au dovedit substantiale: cost prin subscripție, tools native, prompt caching gratuit, schimbare de model cu un flag.

Acest articol descrie patternul, motivele alegerii, și capcanele identificate în operare.

TL;DR

• Un agent custom scris peste SDK trebuie să reimplementeze: tool registration, context management, prompt caching, error recovery, multi-turn loop.
• claude CLI conține deja toate acestea, fiabil, în interfață stabilă.
• Apelat ca subprocess cu input pe stdin și output capturat, devine un runtime complet de agent.
• Beneficii cheie: subscripție în loc de cost per token, tool integration nativă, schimbare de model cu un flag, scrolling de context delegat.
• Capcane: gestionarea sesiunilor lungi, formatarea output-ului pentru parsare, securitatea sandbox-ului.

Problema „pun un agent peste SDK”

Construirea unui agent custom peste un SDK LLM pare directă, dar ascunde complexitate considerabilă:

Tool registration și execution. Trebuie să mapezi numele tool-urilor la funcții, să serializezi/deserializezi argumentele, să gestionezi erorile de execuție, să mapezi rezultatele înapoi la formatul model-ului.

Multi-turn loop. Un agent face: model răspunde, apelează tool, primește rezultat, model răspunde din nou. Acest loop trebuie scris cu gestionare corectă de errori, oprire la limita de tokens, oprire la limita de iterații, recuperare la rate limit.

Context management. Pe măsură ce conversația crește, trebuie să decizi ce păstrezi în context, ce summarizezi, ce arhivezi. Această logică este non-trivială.

Prompt caching. Modelele recente oferă caching pentru system prompts mari. Trebuie să marchezi corect blocurile cacheabile, să verifici hit rate, să gestionezi invalidarea.

Rate limiting și retry. Backoff exponențial, detectarea erorilor temporare vs permanente, fallback la model alternativ.

File system access. Dacă agentul scrie/citește fișiere, trebuie sandbox, gestionare permisiuni, evitare path traversal.

Estimare conservativă: 3-6 luni de muncă pentru a construi un agent custom robust. Și apoi întreținerea continuă.

Soluția: claude CLI ca subprocess

Anthropic distribuie claude ca un CLI complet: instalare locală, autentificare prin contul utilizatorului, capacitate de a citi și scrie fișiere, tool calling intern, context management automat. CLI-ul este deja un agent complet, nu doar un wrapper peste API.

Patternul nostru:

import subprocess

def run_claude_session(task_prompt: str, working_dir: str) -> str:
    proc = subprocess.run(
        ["claude", "--non-interactive", "--allow-tools", "Read,Write,Bash"],
        input=task_prompt,
        capture_output=True,
        text=True,
        cwd=working_dir,
        timeout=600,
    )
    if proc.returncode != 0:
        raise ClaudeRuntimeError(proc.stderr)
    return proc.stdout

Apelul nostru de la nivel aplicație nu vede API-ul Claude direct. Vede un subprocess care primește un task, lucrează cu file system, returnează rezultat.

Beneficii practice

1. Subscription pricing în loc de cost per token. Un cont Claude Pro / Max are cost lunar fix și permite uz intens. Pentru un agent care face zeci sau sute de invocări pe zi, costul lunar este predictibil și de obicei mai mic decât factura per-token. Pentru lucrul de proiectare („design phase”), unde fiecare invocare poate consuma multe tokens, această economie este semnificativă.

2. Tools native. CLI-ul are deja tools pentru: Read, Write, Edit, Bash, Glob, Grep, WebFetch. Nu trebuie să le re-implementăm. Aplicația noastră primește output-ul final; munca de coordonare s-a întâmplat în CLI.

3. Context management automat. CLI-ul gestionează compactarea contextului când se apropie de limită. Nu trebuie să scriem logică custom pentru a decide ce păstrăm.

4. Prompt caching. CLI-ul folosește caching de prompt pentru system prompt și tools. Beneficiul economic apare automat, fără să configurăm manual.

5. Schimbare de model. claude --model sonnet-X schimbă modelul. Aplicația nu se modifică. Pentru cost-aware routing, pasăm modelul ca parametru.

6. Audit log nativ. CLI-ul scrie istoricul sesiunii în jsonl pe disk. Pentru audit, citim aceste fișiere.

7. Updates fără re-engineering. Când Anthropic îmbunătățește CLI-ul (tools noi, performance, fix-uri), aplicația beneficiază imediat. Echipa noastră nu mentine cod CLI-level.

Cum funcționează în arhitectura noastră

În arhitectura agent-orchestrator descrisă în articole anterioare, un orchestrator primește o cerere, construiește un plan, cere aprobare, și după aprobare execută. Faza de execuție pas-cu-pas este unde apare CLI-ul.

Utilizator: cere prin Telegram → orchestrator (model premium prin API) →
  produce plan → cere aprobare prin Telegram →
  utilizator aprobă →
  orchestrator pornește un subprocess `claude` cu instrucțiunea „execută pasul 1" →
  CLI Claude lucrează: citește fișiere, scrie configurații, apelează shell, raportează →
  orchestrator citește output, validează, trece la pasul 2 →
  ...

Orchestrator-ul este creierul; CLI-ul este executorul. Comunicarea este prin stdin/stdout/file system.

Capcane identificate

Capcană 1: sesiuni lungi care depășesc context. O sesiune claude lungă consumă context. Dacă pasul de executat este foarte mare, CLI-ul poate ajunge la limită. Soluție: descompunere a planului în pași mai mici, fiecare pas într-o sesiune CLI separată. Comunicarea între pași este prin file system și prin parametri pasați la sesiunea următoare.

Capcană 2: parsarea output-ului pentru aplicație. CLI-ul produce text natural în limbajul utilizatorului. Aplicația vrea structuri. Soluție: cere CLI-ului să scrie output structurat în fișier specific (de ex. /tmp/claude_result.json), iar aplicația citește fișierul. Sau folosește mod --output-format json dacă disponibil.

Capcană 3: securitatea sandbox-ului. CLI-ul are acces la file system. Pentru un agent care rulează pe infrastructura noastră, asta este OK. Pentru un agent care servește clienți externi, este obligatoriu rularea într-un container izolat per cerere, cu volume montate doar la directoarele relevante.

Capcană 4: erori non-deterministe. Două invocări claude cu input identic pot produce output diferit (modelul lingvistic are stochasticitate). Pentru testare, folosiți --temperature 0 și verificați doar invariantele (a fost creat fișierul X? Da/Nu).

Capcană 5: dependența de versiunea CLI. O actualizare CLI poate schimba comportament. Soluție: pin versiunea CLI în deploy, testează înainte de upgrade, includeți version în logul de audit.

Capcană 6: pricing tier limits. Conturile cu subscripție au limite zilnice de utilizare. Dacă agentul vostru are nevoie de volume mari, ori scalez peste mai multe conturi, ori folosiți API direct. Conturi multiple sunt OK doar dacă termenii de utilizare ai providerului permit.

Comparație cu frameworks existente

Frameworks ca LangChain, LlamaIndex, AutoGen, CrewAI au merit pentru anumite cazuri (research, prototipare rapidă, scenarii specifice). Pentru un agent ops production, observațiile noastre după evaluare:

• Frameworks adaugă layer de abstracție care complicăm debugging
• Deciziile lor de design nu se aliniază mereu cu cerințele noastre (ex: tool calling parallel vs serial)
• Updates ale frameworks pot rupe agentul custom
• Documentația tinde să fie prematur (sau retroactiv) pe versiuni vechi

Folosirea CLI-ului direct elimină acest layer. Aplicația comunică direct cu CLI-ul oficial Anthropic. Mai puține piese mobile.

Când patternul nu se potrivește

Patternul claude CLI ca runtime nu este universal:

• Dacă rulați pe model non-Claude exclusiv, CLI-ul nu se aplică (folosiți alt CLI similar dacă există, sau adapter direct la API).
• Dacă latența per cerere trebuie să fie sub 1 secundă, subprocess startup time poate fi prohibitiv. Pentru cereri lente (5-30 sec), este nesemnificativ.
• Dacă aveți cerință strict on-prem fără apel cloud, CLI-ul Claude apelează API cloud al Anthropic. Pentru on-prem total, folosiți model local și CLI corespunzător sau adapter direct.

În alte cazuri, pattern-ul prinde mai mult din ce e necesar pentru un agent decât majoritatea framework-urilor.

Concluzie

Construirea unui agent AI peste un CLI matur (Claude Code, sau echivalente pentru alte modele) reduce timpul de dezvoltare de la luni la zile. Renunțați la fantezia de a controla fiecare aspect al loop-ului LLM și beneficiați de munca echipei care a construit CLI-ul. Aplicația vostră se concentrează pe ce este unic — orchestrare, business logic, integrări specifice — în loc să reinventeze infrastructure de tool calling.

Este patternul pe care îl recomandăm clienților care nu au cerințe stricte de a evita Anthropic. Pentru clienții cu astfel de cerințe, BYO-LLM cu adapters minim este alternativa.

Articole conexe

• Pattern BYO-LLM cu adapters minimi
• Cost-aware LLM routing
• Arhitectura propose-then-act pentru agenți AI
• Pillar IRIS — agentul orchestrator CAI Technology

Surse externe

• Claude Code documentation — referință oficială pentru CLI și tools native
• Anthropic Messages API reference — pentru cazurile în care folosiți API direct
• Anthropic prompt caching — caching folosit nativ de CLI
• Python subprocess documentation — patternul standard pentru a apela CLI-uri din aplicație
• „Constitutional AI” — Anthropic, arXiv 2212.08073 — context de design al modelelor folosite de CLI

Următorul pas

Dacă echipa dvs. evaluează arhitectura unui agent AI și e curioasă dacă pattern-ul CLI-ca-runtime se potrivește, vă oferim o consultație tehnică de 30 minute fără cost.