Tutorial Cursor Agent Mode: Construirea unui REST API cu GPT-5.6 Sol

Ce este Cursor?

Cursor a început ca un VS Code cu funcții AI cusute pe deasupra și încă așa arată la suprafață. Editorul, arborele de fișiere, terminalul, extensiile, toate familiare. 

Ce a fost reconstruit dedesubt este presupunerea că AI-ul nu doar răspunde la întrebări pe margine, ci chiar lucrează alături de tine, motiv pentru care ai modul agent, indexarea codebase-ului, un selector de modele care îți permite să schimbi între modele frontieră în timpul sesiunii și completări inline care îți prezic următoarea mișcare pe baza întregului context al a ceea ce ai făcut.

Dacă vrei să aprofundezi cele mai noi funcții ale Cursor, îți recomand să citești tutorialele noastre despre Cursor Automations și Cursor SDK.

Ce este GPT-5.6?

GPT-5.6 este cea mai nouă generație de modele a OpenAI și nu e un singur model, ci trei: Sol, Terra și Luna. Aceste nume sunt trei niveluri distincte de capabilitate, înlocuind vechea etichetă „Instant”.

Pe scurt, familia arată așa:

• Sol este vârful de gamă și cel mai puternic dintre cele trei. Este singurul nivel care deblochează noul efort de raționare max și modul ultra, și aici sunt cele mai mari câștiguri pe coding, biologie și securitate cibernetică.

• Terra este implicitul de zi cu zi. OpenAI îl poziționează ca fiind competitiv cu GPT-5.5 la aproximativ jumătate din preț.

• Luna este nivelul rapid și ieftin pentru muncă de volum mare sau sensibilă la latență, și e mai puternic decât sugerează prețul.

Pentru un walkthrough de coding, Sol este nivelul care contează, așa că asta folosim aici. Două setări pe Sol sunt noi și merită să știi pe care o vei atinge de fapt. max este un nivel de efort de raționare peste xhigh care permite unui singur agent să petreacă mai mult timp pe o problemă dificilă și este treapta de sus pe care o setezi în Cursor. ultra, care împarte munca între subagenți paraleli, postează cele mai bune scoruri de benchmark ale OpenAI (91,9% pe Terminal-Bench 2.1) dar rulează doar în Codex și API, deci nu îl vei găsi în selectorul Cursor.

Pentru tabelul complet de benchmark și prețurile pe trei niveluri, consultă ghidul nostru GPT-5.6 Sol, Terra și Luna.

Cum accesezi și configurezi GPT-5.6 Sol în Cursor

GPT-5.6 Sol este disponibil în selectorul de modele din Cursor și e un lucru de știut din start: la fel ca celelalte modele frontieră recente din Cursor, Sol rulează doar în Max Mode al Cursor. Asta înseamnă că folosește fereastra de context completă și toate uneltele și este tarifat pe utilizare, nu per cerere, așa că urmărește consumul de tokeni în timpul rulărilor lungi.

Pentru a selecta modelul:

1. Deschide panoul agentului cu Cmd+L (Mac) sau Ctrl+L (Windows/Linux).
2. Click pe butonul Model din partea de jos a zonei de input (arată numele modelului curent lângă o pictogramă mică).
3. Dezactivează Auto dacă e activ.
4. Găsește GPT-5.6 Sol în listă și apasă Edit lângă el.
5. Se deschide un panou în dreapta, unde poți seta independent fereastra de context, nivelul de raționare și comutatorul de viteză.

Alegerea efortului de raționare potrivit

Selectarea lui Sol alege modelul; efortul de raționare decide cât de intens gândește pe o sarcină dată. Poți alege între:

• None
• Low
• Medium
• High
• Extra High
• Max

None și Low sunt cele mai rapide și mai ieftine, suficiente pentru autocomplete sau un refactor mecanic unde știi deja ce vrei. 

High și Extra High durează mai mult pentru că încep prin a gândi efectiv prin problemă, iar diferența se vede mai ales când ceri agentului să planifice ceva care traversează mai multe fișiere sau să depaneze un eșec unde sursa nu e imediat evidentă. 

Max stă deasupra lui Extra High și oferă unui singur agent cel mai mult timp pentru a lucra la o problemă dificilă. Modul multi-agent ultra al lui Sol există doar în Codex și API, deci nu îl vei vedea în selectorul Cursor.

Un avertisment dacă vii de la GPT-5.5: nivelurile nu se suprapun. Ghidul OpenAI este să începi cu un nivel mai jos decât ești obișnuit pe o sarcină cunoscută și să îl ridici doar dacă rezultatul o cere. Așa am procedat mai jos, deci câțiva pași rulează la un efort mai mic decât ar fi avut tutorialul echivalent pe 5.5.

Pe parcursul pașilor practici de mai jos, îți voi sugera ce nivel de raționare are cel mai mult sens pentru fiecare sarcină, dar simte-te liber să experimentezi cu setări diferite și să vezi cum se schimbă rezultatul.

Alegerea dimensiunii ferestrei de context și a modului de viteză

Poți alege între o fereastră de context de 272K și 1M și poți activa modul Fast pentru a genera tokeni la aproximativ 1,5x viteză pentru cam 2,5x cost în credite. Pentru un dialog interactiv unde aștepți răspunsuri, Fast merită adesea. Pentru o sarcină mai lungă în fundal, unde ai delegat ceva și faci alte lucruri cât timp rulează, îl poți lăsa oprit.

Configurarea Cursor

Hai să configurăm proiectul în Cursor.

Condiții prealabile și configurare inițială

Ai nevoie de un abonament plătit Cursor (Pro sau mai sus) pentru GPT-5.6 Sol, iar pentru că Sol rulează în Max Mode, tarifarea pe utilizare trebuie activată pe contul tău. Python 3.11+ este singura altă dependență locală necesară pentru acest proiect. Dacă Cursor nu este înstalat încă, ia-l de pe cursor.com, autoentifică-te și apoi dintr-un terminal:

mkdir budget-api && cd budget-api
git init
cursor .

Panoul Agent este în dreapta, iar exploratorul de fișiere din stânga nu arată încă niciun fișier, exact locul de unde vrei să pornești înainte să lași agentul să construiască structura.

Navigarea suprafețelor AI din Cursor

Înainte să intri în construirea propriu-zisă, merită să știi care sunt cele trei moduri principale de interacțiune și când are sens fiecare, pentru că folosirea celui greșit creează fricțiune ușor de evitat.

Completarea inline este stratul de autocomplete în fundal. Pe măsură ce tastezi, apar sugestii gri bazate pe ce scrii și contextul din jur în fișier, iar tu le accepți cu Tab. Nu o invoci; pur și simplu apare. Acesta este modul potrivit când scrii manual cod și vrei ca modelul să reducă numărul de apăsări de taste fără să îți întrerupă fluxul.

Modul Ask este locul unde poți pune modelului să îți citească fișierele și să răspundă la întrebări fără să facă modificări. Gândește-te la el ca la a cere unui coleg să se uite la cod și să îți spună ce vede. E deosebit de util când ești într-un codebase necunoscut, încerci să înțelegi de ce ceva a fost scris într-un anumit fel sau doar îți gândești o abordare înainte să te angajezi în ea.

Modul Agent este ceea ce alimentează întregul acest tutorial. Într-o sesiune de agent, modelul editează fișiere, rulează comenzi în terminal, instalează pachete, execută suita ta de teste, citește ieșirea și reia pe eșecuri, toate într-un singur fir continuu. Acesta este modul în care delegi o sarcină, nu doar întrebi despre ea, iar calitatea a ceea ce primești înapoi crește direct cu cât de mult context îi dai din start. Poți vedea selectorul de mod Agent în partea stângă jos a panoului în captura de ecran de mai sus.

Stabilirea îndrumărilor specifice proiectului cu AGENTS.md

Scrii tu acest fișier, deci încă nu folosim modelul. Comută mai întâi pe High, deoarece următorul prompt este când agentul îl citește. Majoritatea sesiunilor cu agenți deraiază nu pentru că modelul a greșit, ci pentru că nu știa ceva specific proiectului și a ghicit: framework-ul tău, convențiile de denumire, ce fișiere sunt interzise, cum să verifice schimbările.

Asta face AGENTS.md: un README pentru agent, unde notezi ce e evident pentru tine dar invizibil pentru model. AGENTS.md a început ca o inițiativă OpenAI în 2025 și este acum standardul cross-tool pentru fișiere de instrucțiuni pentru agenți (parte din Agentic AI Foundation a Linux Foundation, alături de MCP de la Anthropic), așa că merită învățat o dată și folosit peste tot.

Creează un fișier numit AGENTS.md la rădăcina proiectului cu următoarele, pentru a-ți seta stack-ul de unelte, convențiile de cod și limitele:

# AGENTS.md

## Stack
Python 3.11, FastAPI, SQLModel, SQLite (via aiosqlite), pytest, httpx

## Conventions
- All endpoints under /api/v1/
- Pydantic models in app/models.py
- Database logic in app/database.py
- Route handlers in app/routers/
- Type hints required on all function signatures
- Explicit imports only, no wildcards

## Boundaries
- Do not delete or modify any file in tests/ without asking first
- Do not change the DATABASE_URL; it reads from .env
- Never touch pyproject.toml dependencies without showing the diff first

## Verification
Before considering any task complete:
  pytest tests/ -v
  ruff check .
Both must pass.

Secțiunea despre limite este partea pe care oamenii o sar cel mai des, și este totodată cea mai importantă. Fără ea, agenții mai decid ocazional să „ajute” reorganizând sau curățând lucruri pe care nu le-ai cerut. Să îi spui modelului ce e interzis este la fel de util ca să îi spui ce are de făcut.

AGENTS.md este standardul cross-tool, dar dacă vrei echivalentul nativ Cursor care face același lucru prin fișiere .mdc cu scop restrâns, tutorialul nostru Cursor Rules parcurge construirea unui set pentru un proiect web Python.

Construirea unui API de urmărire a bugetului cu GPT-5.5

Proiectul este un REST API pentru urmărirea intrărilor de buget personal. Poți crea intrări, le poți lista cu filtrare opțională pe categorie, le poți șterge și poți obține un sumar lunar al cheltuielilor. 

E destul de simplu de urmărit fără să te pierzi în logica domeniului, dar implementarea implică un strat de bază de date, validare de input, modele de răspuns tipate și mai mulți handleri de rute care lucrează împreună, suficient cât să vezi ce face agentul într-o sesiune reală pe mai multe fișiere.

Pasul 1: Scaffold pentru structura proiectului

Deschide panoul agentului și setează efortul de raționare pe High înainte să trimiți ceva. Planul pe care agentul îl produce înainte de a scrie orice cod este la fel de util ca raționamentul din spatele lui, iar un răspuns superficial în acest stadiu înseamnă decizii structurale pe care le vei descurca mai târziu. Continuă trimițând asta ca primul tău prompt:

Set up a FastAPI project for a budget tracker API using SQLModel with 
async SQLite. Structure it with separate files for models, database, and 
routes under an app/ directory. Set up pyproject.toml with uv, install 
dependencies, and create a main.py that starts the app.

Before writing any code, show me the planned directory structure 
and wait for my approval.

Ultima linie merită păstrată în toate prompturile tale non-triviale pentru agenți. Să ceri planul înainte de execuție te costă poate 15 secunde de citit, dar îți permite să prinzi decizii structurale înainte să se propage printr-o duzină de fișiere. 

GPT-5.6 Sol la raționare High produce planuri suficient de specifice ca să fie cu adevărat utile, nu rezumate vagi, iar să revizuiești structura acum e mult mai rapid decât s-o reorganizezi mai târziu.

Agentul propune layout-ul proiectului și așteaptă aprobarea înainte să scrie vreun fișier.

După ce răspunzi cu ceva de genul „Arată bine, continuă”, agentul începe să construiască. Poți urmări arborele de fișiere din stânga cum se populează în timp real pe măsură ce creează fișiere, în timp ce terminalul de jos arată uv instalând pachete.

Agentul a creat un pyproject.toml ca parte a scaffold-ului, cu conținutul fișierului afișat ca adăugare nouă.

După ce scaffold-ul se termină, ia-ți un minut să deschizi app/models.py și app/database.py înainte de a continua. Confirmă că modelul BudgetEntry are cel puțin câmpurile id, amount, description, category și date și că database.py configurează engine-ul SQLite async fără nimic neobișnuit. 

Dacă ceva pare în neregulă, spune asta în următorul mesaj în loc să continui. Corecțiile în acest stadiu sunt ieftine; după ce au fost modificate douăzeci de fișiere, nu mai sunt.

Pasul 2: Implementează endpoint-urile de bază

Păstrează efortul la High sau încearcă mai întâi Medium, deoarece Sol pe Medium gestionează munca coordonată pe mai multe fișiere care ar fi necesitat High pe GPT-5.5. Trimite promptul de implementare:

Implement endpoints for budget entries under /api/v1/entries/. Include:
- POST /api/v1/entries/ to create a new entry, returning 201
- GET /api/v1/entries/ to list all entries, with an optional ?category= filter
- DELETE /api/v1/entries/{id} to delete an entry, returning 404 if not found

Use typed Pydantic response models and dependency injection for the DB session.
After implementing, start the app and confirm the /docs endpoint loads.

Agentul atinge models.py, database.py, routers/entries.py și main.py într-o singură trecere coordonată. Pe măsură ce termină fiecare fișier, Cursor arată conținutul nou evidențiat în editor ca să îl poți revizui înainte să accepți. Vei vedea controalele Undo/Keep în partea de jos a fiecărui fișier schimbat.

Captura de ecran arată routerul entries.py după ce agentul îl implementează, împreună cu confirmarea agentului că a pornit serverul și că endpoint-ul /docs s-a încărcat corect. 

După ce accepți implementarea și serverul rulează, deschide http://localhost:8000/docs în browser ca să confirmi că totul e conectat corect.

Documentația auto-generată FastAPI de la /docs, arătând toate cele trei endpoint-uri înregistrate corect. 

Pasul 3: Adaugă validare pentru categorie

Pentru acest al treilea pas, poți coborî raționarea modelului la Low sau Medium. Adăugarea unui enum și a două teste este suficient de auto-conținută și previzibilă încât nu ai nevoie ca modelul să consume cicluri suplimentare de deliberare. 

În prezent, API-ul acceptă orice șir ca și categorie, ceea ce înseamnă că vei ajunge rapid la date inconsistente. Hai să reparăm asta:

Budget entries should only accept these categories: 
food, transport, housing, entertainment, health, other.

Reject any entry with an invalid category using a 422 status and a clear 
error message. Use a Python Enum for the category type. 
Add tests for both a valid category submission and an invalid one in tests/test_entries.py.

Agentul va adăuga un enum de categorii în models.py și va actualiza modelul Pydantic pentru a-l folosi. Deoarece Pydantic validează automat față de enum, categoriile invalide sunt respinse înainte să ruleze handlerul rutei.

Ar trebui să scrie alături două teste: unul care confirmă că o categorie validă se salvează corect, altul care confirmă că o categorie invalidă revine cu un 422.

Folosirea referinței @

După ce accepți aceste schimbări, încearcă funcția de context @ din Cursor ca să pui rapid o întrebare de verificare:

@app/models.py Does the CategoryEnum cover all six categories I listed?

Tastează @ în panoul agentului pentru a deschide un picker de fișiere, iar după ce selectezi app/models.py, conținutul acelui fișier este tras direct în prompt, fără ca agentul să fie nevoit să îl caute sau să facă presupuneri despre cale.

Pasul 4: Construiește endpoint-ul de sumar lunar

Revino aici la High. Interogarea de agregare cere agentului să raționeze împreună despre filtrare, grupare și designul modelului de răspuns, iar dacă greșește oricare dintre ele, înseamnă să atingă din nou toate cele trei fișiere. Cu CRUD-ul de bază funcțional, adaugă endpoint-ul de sumar:

Add a GET /api/v1/entries/summary endpoint that accepts month (1-12) and year as query parameters. 
It should return total spending per category for that month and an overall total. 
Use a typed Pydantic response model. 
If no entries exist for the requested month, return an empty summary with zero totals rather than a 404.

Aceasta este o sarcină de bază de date mai interesantă pentru că necesită o interogare filtrată cu agregare, nu un simplu select-all. Uită-te cum structurează agentul interogarea în database.py; ar trebui să folosească interfața de interogare a SQLModel, nu SQL brut, iar rezultatul ar trebui să se potrivească natural pe modelul de răspuns definit în models.py.

După ce accepți schimbările, scrie singur un test pentru acest endpoint în test_entries.py. Creează două intrări într-o lună specifică, apelează endpoint-ul de sumar pentru acea lună și verifică dacă totalurile se potrivesc. Să îl scrii manual, mai degrabă decât să ceri agentului, e o modalitate bună să te familiarizezi cu structura clientului de test și a fixture-elor.

Fișierul test_entries.py arată testele de validare a categoriilor scrise de agent alături de funcția test_monthly_summary scrisă manual. 

Pasul 5: Rulează bucla de validare

Low sau Medium funcționează bine aici; rularea testelor și repararea problemelor de lint este muncă reactivă, agentul citește ieșirea erorilor și aplică remedieri țintite, mai degrabă decât să ia decizii arhitecturale reale. Predă testarea înapoi agentului:

Run pytest tests/ -v and fix any failing tests. 
Do not modify test assertions to make them pass, fix the implementation instead.
Once all tests pass, run ruff check . and fix any linting issues.

Urmărește panoul agentului în timp ce transmite ieșirea pytest. 

Dacă ceva eșuează, agentul citește traceback-ul, identifică fișierul care a introdus problema și aplică remedierea, toate în cadrul aceleiași sesiuni. Nu copiezi eroarea într-un mesaj nou; întreaga buclă de depanare și remediere are loc într-un singur fir continuu.

Captura arată agentul raportând după bucla completă de validare. În acest caz, verificarea ruff a întâmpinat o problemă de rezoluție a interpretului cauzată de un nealiniament pyenv/.python-version pe mașina locală, nu o problemă de cod. 

Merită notat ce s-a întâmplat aici: agentul a întâlnit o problemă de mediu fără legătură cu codul pe care l-am scris, a raționat cauza și a găsit o soluție alternativă fără a fi solicitat. Acest tip de rezolvare contextuală a problemelor prin eșecuri de unelte este exact locul unde GPT-5.6 Sol se detașează de modelele anterioare.

Merită, de asemenea, să incluzi „nu modifica aserțiunile testelor ca să le faci să treacă” în fiecare prompt de validare pe care îl scrii. Fără acea instrucțiune, agenții iau ocazional calea cea mai ușoară și slăbesc ce verifică un test în loc să repare comportamentul real.

Pasul 6: Trecere de code review

Setează din nou raționarea pe High înainte să trimiți asta, sau Extra High/Max dacă vrei ca Sol să sape pe cazuri-limită pe care o singură trecere High le-ar putea trece în grabă. În acest pas, o raționare superficială creează un fals sentiment de siguranță; vrei ca modelul să lucreze efectiv prin toate potențialele probleme, nu doar să facă pattern-match pe cele mai evidente.

Înainte să declari proiectul gata, folosește agentul pentru un review:

Review the current codebase and report on:
1. Query params or path params that are missing validation
2. Database sessions that might not be closing properly
3. Endpoints returning incorrect HTTP status codes
4. Any places where user input reaches the database without going 
   through the ORM

Do not make any changes yet. List each issue with file and line number.

Agentul a constatat că DELETE /api/v1/entries/{entry_id} returnează corect codurile 204 și 404 (cu referințe fișier:linie), că rutele GET se bazează pe 200 implicite corecte și a confirmat că niciun input de la utilizator nu ajunge la baza de date în afara ORM-ului.

După ce ai revizuit lista, trimite follow-up-ul pentru a aplica remediile:

Apply the fixes for the status code issues and the session handling. 
Skip any rate-limiting suggestions, that's out of scope for this version.
Run the tests again after applying.

Pasul 7: README și workflow de CI

Două ultime retușuri pentru a încheia proiectul cum trebuie. Poți coborî raționarea modelului la Low pentru ambele. Structura README-ului este previzibilă, iar YAML-ul de CI este practic boilerplate, deci nu e nimic de raționat, iar să plătești pentru raționare înaltă aici înseamnă credite irosite.

Write a README.md with setup instructions, a table of all endpoints (method, path, description), and example curl commands for each endpoint.

Și apoi:

Create a .github/workflows/ci.yml that runs pytest and ruff on Python 3.11 for every push and pull request to main.

După toți cei șapte pași, structura proiectului arată astfel:

Gânduri finale

Ce am construit aici este un API mic, dar fluxul de lucru scalează la orice. 

Pune AGENTS.md la locul lui înainte ca agentul să atingă vreun fișier. Cere planul înainte de execuție pentru orice non-trivial. Etapelează-ți prompturile, ca să ai puncte naturale de verificare, nu un singur diff uriaș de revizuit dintr-odată. Folosește @filename când vrei să întrebi ceva țintit despre un fișier anume. Și rulează o trecere de review înainte să consideri o sarcină încheiată, pentru că aproape întotdeauna vei prinde ceva.

GPT-5.6 Sol în Cursor este vizibil mai bun decât combinațiile anterioare la a rămâne pe sarcină pe sesiuni lungi, a prinde inconsistențe între fișiere și a ști când să se oprească și să ceară confirmare în loc să înainteze pe ceva distructiv. Dar modelul este doar o parte a poveștii. Contextul pe care i-l dai din start, buclele de validare pe care le rulezi și trecerea de review de la final — de acolo vine îmbunătățirea reală a calității rezultatelor.

O regulă utilă pentru nivelurile de raționare: folosește High pentru decizii de arhitectură, coordonare pe mai multe fișiere și depanarea a ceva ne-evident; folosește Medium sau Low pentru documentație, boilerplate și editări într-un singur fișier unde doar ceri modelului să tasteze. Ia în considerare Extra High sau Max pentru code reviews și acolo unde greșelile sunt mai costisitoare decât o rulare temeinică a agentului.