Cum integrezi Claude si GPT-5 intr-o aplicatie SaaS

01Provider abstraction layer: de ce si cum

Prima regula a integrarii serioase de LLM-uri intr-un SaaS este sa nu vorbesti niciodata direct cu SDK-ul vendor-ului din business logic. Construiesti un strat de abstractie peste Claude, GPT-5, Gemini si modelele open-source self-hosted, care expune o interfata uniforma de tipul generate, stream, embed si tool. In spate, fiecare provider are propriul adapter care normalizeaza diferentele de format, mapeaza erorile la o ierarhie comuna si traduce optiunile specifice intr-un dictionar tipat.

Beneficiile sunt majore. Poti comuta intre Claude Sonnet 4.5 pentru reasoning si GPT-5 mini pentru task-uri rapide cu o singura linie de configurare per feature. Poti rula A/B testing intre modele pe acelasi prompt si poti masura impactul in conversie sau in calitatea iesirilor. Poti adauga rapid un nou provider cand apare un model competitiv, fara sa rescrii business logic. Si, foarte important, poti construi un router inteligent care alege automat modelul potrivit in functie de complexitatea cererii.

In implementarile Blackbone, stratul de abstractie traieste intr-un pachet separat numit ai-core, scris in TypeScript cu zod si versioneaza contractele cu semver intern. Fiecare adapter implementeaza aceeasi interfata Provider cu metode generate, stream si tool-uri, iar configuratia per feature trece printr-un registry care permite hot-swap fara redeploy, foarte util cand un provider cade temporar.

• →Interfata uniforma: generate, stream, embed, callTool, countTokens
• →Adaptere izolate per provider, fara leak de tipuri specifice in business logic
• →Configuratie per feature in registry persistent, nu in cod
• →Router care alege model in functie de cost, latenta si calitate ceruta

02Streaming cu Server-Sent Events si backpressure

Utilizatorii moderni se asteapta ca raspunsul AI sa apara token cu token, ca in ChatGPT. Implementarea naiva care asteapta raspunsul complet inainte sa il trimita catre client adauga secunde de latenta perceputa si distruge experienta. Solutia standard este Server-Sent Events, suportat nativ de browsere si simplu de proxy-at prin Nginx sau Cloudflare. WebSocket-urile sunt overkill pentru cazul unidirectional al raspunsului LLM si introduc complexitate inutila in load balancer.

Implementarea trebuie sa trateze corect cateva probleme subtile. Backpressure-ul: daca clientul citeste mai incet decat trimite serverul, bufferele se umfla si memoria explodeaza. Solutia este streaming bidirectional cu acknowledgment periodic si throttling pe partea de server. Deconectarile: clientii pe mobil pierd reteaua frecvent, iar serverul trebuie sa detecteze rapid disconnect-ul si sa anuleze inferenta in curs cu abort signal catre provider, altfel platesti tokeni pentru raspunsuri care nu ajung nicaieri.

Pe partea de format, recomandarea noastra este sa nu trimiteti tokeni bruti, ci evenimente structurate de tip start, delta, tool-call, tool-result, error si done. Fiecare eveniment poarta un message-id si un sequence-number care permit clientului sa reconstituie corect statea si sa reia la nevoie. Pentru SaaS multi-tenant, fiecare eveniment include si tenant-id si user-id pentru auditabilitate, mascate inainte de logging.

03Structured outputs cu Zod si validare stricta

Multe feature-uri au nevoie ca LLM-ul sa returneze JSON cu o structura exacta: un obiect cu campuri specifice, enumerari validate, array-uri tipate. Zod-ul devine sursa de adevar pentru aceste contracte. Definim schema o singura data in TypeScript, derivam tipul, generam JSON Schema pentru OpenAI structured outputs sau pentru Claude tool-uri si folosim aceeasi schema pentru a valida raspunsul la primire. Daca raspunsul nu trece validarea, trimitem un retry cu mesajul de eroare in context, iar dupa trei esecuri esuam controlat catre o varianta de degradare.

Pentru GPT-5 folosim modul response_format cu json_schema, care garanteaza la nivel de model ca iesirea este JSON valid si respecta schema. Pentru Claude folosim tool use cu schema input_schema, ceea ce ofera acelasi nivel de garantie. Diferenta este ca Claude prefera sa primeasca instructiunile in mesajul de sistem, iar OpenAI le accepta direct in parametrii apelului. Stratul de abstractie ascunde aceasta diferenta si expune o singura metoda generateStructured care primeste schema Zod.

Capcana cea mai frecventa este sa pui schema prea stricta de la inceput. Daca cere validation pentru 30 de campuri obligatorii cu enum-uri lungi, rata de esec creste mult, mai ales pe modele mai mici. Recomandarea este sa incepem cu schema laxa, sa masuram rata de esec in productie si sa strangem progresiv constrangerile. Echipa Blackbone are un set intern de patterns pentru schema design care minimizeaza retries si reduce costul.

• →O singura schema Zod, derivata in TypeScript si in JSON Schema
• →Validare stricta la primire, cu retry inteligent pe eroare
• →Schema in tool input pentru Claude, in response_format pentru GPT-5
• →Fallback controlat catre raspuns degradat dupa 3 esecuri

04Function calling si orchestrare de tool-uri

Function calling este mecanismul prin care LLM-ul nu raspunde direct utilizatorului, ci cere sistemului sa execute o actiune si sa returneze rezultatul. Tipic, definim 5-50 de tool-uri per agent, fiecare cu nume, descriere si schema de input. LLM-ul decide cand sa apeleze un tool, sistemul executa, returneaza rezultatul si LLM-ul continua reasoning-ul. Pentru SaaS, tool-urile sunt apeluri catre API-urile interne: cauta utilizatori, citeste setari, creeaza tichete, ruleaza interogari pe baza de date.

Provocarile reale apar la orchestrare. Cum gestionezi tool-uri care dureaza secunde, fara sa blochezi streaming-ul? Cum tratezi tool-uri care esueaza tranzient? Cum impui rate limits per utilizator si per tool? Cum auditezi ce tool-uri a apelat agentul si cu ce parametri? Solutia este un middleware de tool execution care valideaza input-ul, ruleaza tool-ul cu timeout, captureaza erorile, le transforma in raspunsuri pe care LLM-ul le poate reasona si emite evenimente catre stratul de observability.

Pentru tool-uri care modifica state, recomandarea ferma este sa adaugi un strat de confirmare. LLM-ul nu executa direct tool-ul, ci propune actiunea, iar utilizatorul confirma in UI inainte de executie. Pentru tool-uri citire poti fi mai liberal, dar tot impui rate limit, idempotenta si masking de PII in logging. La proiectele livrate de noi, am vazut incidente costisitoare cand un agent a apelat tool-uri de scriere intr-o bucla din cauza unui prompt prost taiat.

05Retries, backoff si circuit breakers

Providerii LLM au incidente. Rate limits, timeout-uri, erori 500 tranziente, overloaded responses. Un cod de productie matur nu lasa exceptia sa propage catre user, ci o trateaza inteligent. Folosim exponential backoff cu jitter pentru retry, plafonat la maxim trei incercari pe acelasi provider pentru a nu balona latenta. La 429 rate limit asteptam intervalul recomandat in header daca este disponibil, altfel folosim un backoff conservator de 1, 2, 4 secunde cu jitter de plus minus 30%.

Pentru rezilienta reala adaugam un strat de fallback cross-provider. Daca Claude Sonnet 4.5 esueaza de trei ori, retrimitem cererea catre GPT-5 cu acelasi prompt normalizat. Stratul de abstractie face acest fallback transparent, cu un mesaj de log clar pentru observability. Pentru feature-urile critice, ca generarea de continut pentru o pagina checkout, fallback-ul nu este optional, este o cerinta de productie.

Circuit breakers protejeaza sistemul cand un provider intra in degradare prelungita. Daca rata de eroare pe un provider depaseste 20% in fereastra de 60 de secunde, deschidem circuit-ul si redirectionam tot traficul catre fallback timp de cateva minute, dupa care testam cu cereri timide. Aceasta arhitectura simpla a salvat zeci de mii de euro in apeluri esuate la clientii nostri in incidentele majore din 2025 si 2026.

• →Retry cu exponential backoff plus jitter, plafonat la 3 incercari
• →Fallback cross-provider transparent prin stratul de abstractie
• →Circuit breakers per provider, deschise la peste 20% erori in 60s
• →Dead letter queue pentru cereri care esueaza definitiv, cu replay manual

06Prompt caching, cost tracking si guardrails financiari

Prompt caching-ul Anthropic este cea mai mare optimizare de cost a anului 2026 pentru SaaS cu prompturi de sistem lungi. Mecanismul memoreaza prefix-ul prompt-ului pentru 5 minute si reduce costul tokenilor cached cu pana la 90%, iar latenta scade cu 50-80%. Conditia este sa structurezi prompt-ul ca prefix stabil urmat de partea variabila, sa atingi pragul minim de 1.024 tokeni cached si sa marchezi corect blocurile cache_control. Pentru un SaaS cu prompt sistem de 6.000 tokeni si milioane de cereri pe luna, economia ajunge la zeci de mii de dolari.

Cost tracking-ul granular este obligatoriu, nu optional. Fiecare apel LLM trebuie sa scrie intr-o tabela de usage cu user-id, tenant-id, feature, provider, model, input-tokens, output-tokens, cached-tokens si cost calculat. Avem nevoie de aceste date pentru billing-ul intern, pentru detectia anomaliilor si pentru optimizarea fiecarui feature in parte. La un client de-al nostru, analiza pe usage table a relevat ca 4% dintre utilizatori generau 71% din costul total, ceea ce a dus la rebalansarea planurilor de pret si recuperarea marjei.

Guardrails financiare ferme protejeaza marja produsului. Definim quote-uri lunare per plan, hard caps per zi pentru a opri abuse-ul si alert-uri proactive cand un utilizator depaseste 80% din quota. Inainte de fiecare apel verificam quota si esuam controlat daca este depasita. Pentru workflow-uri agentic-style care pot face apeluri in lant, impunem si un buget pe sesiune, masurat in dolari, care opreste agentul cand este atins indiferent de starea task-ului.