Tutorial su Cursor Agent Mode: crea una REST API con GPT-5.6 Sol

Cos’è Cursor?

Cursor è nato come VS Code con funzioni AI integrate, e in superficie assomiglia ancora a quello. L’editor, l’albero dei file, il terminale, le estensioni: tutto familiare. 

Quello che è stato ricostruito sotto il cofano è l’assunto che l’AI non stia solo rispondendo a domande a lato, ma stia effettivamente lavorando al tuo fianco, motivo per cui hai la modalità agente, l’indicizzazione del codebase, un selettore di modelli che ti permette di passare tra modelli di frontiera a sessione in corso e completamenti inline che prevedono la tua prossima mossa basandosi sull’intero contesto di ciò che hai fatto.

Se vuoi esplorare più a fondo le funzionalità più recenti di Cursor, ti consiglio di leggere i nostri tutorial su Cursor Automations e Cursor SDK.

Cos’è GPT-5.6?

GPT-5.6 è la nuova generazione di modelli di OpenAI, e non è un solo modello ma tre: Sol, Terra e Luna. Questi nomi rappresentano tre tier di capacità distinti, che sostituiscono la vecchia etichetta "Instant".

Ecco la famiglia in breve:

• Sol è il fiore all’occhiello e il più potente dei tre. È l’unico tier che sblocca il nuovo livello di ragionamento max e la modalità ultra, ed è dove i progressi in coding, biologia e cybersecurity sono maggiori.

• Terra è il predefinito di tutti i giorni. OpenAI lo posiziona come competitivo con GPT-5.5 a circa metà prezzo.

• Luna è il tier veloce ed economico per lavoro ad alto volume o sensibile alla latenza, ed è più forte di quanto suggerisca il prezzo.

Per una walkthrough di coding, Sol è il tier che conta, quindi qui useremo quello. Due impostazioni su Sol sono nuove, ed è utile sapere quale toccherai davvero. max è un livello di sforzo di ragionamento sopra xhigh che permette a un singolo agente di impiegare più tempo su un problema difficile, ed è il gradino più alto che imposti in Cursor. ultra, che suddivide il lavoro tra subagent paralleli, pubblica i migliori numeri di benchmark di OpenAI (91,9% su Terminal-Bench 2.1) ma gira solo in Codex e nell’API, quindi non lo troverai nel selettore di Cursor.

Per la tabella completa dei benchmark e i prezzi a tre tier, dai un’occhiata alla nostra guida a GPT-5.6 Sol, Terra e Luna.

Come accedere e configurare GPT-5.6 Sol in Cursor

GPT-5.6 Sol è disponibile nel selettore dei modelli di Cursor, e c’è una cosa da sapere subito: come gli altri recenti modelli di frontiera di Cursor, Sol gira solo in Max Mode di Cursor. Ciò significa che usa la finestra di contesto completa e tutti gli strumenti, e viene fatturato a consumo piuttosto che per richiesta, quindi tieni d’occhio la spesa in token durante esecuzioni lunghe.

Per selezionare il modello:

1. Apri il pannello dell’agente con Cmd+L (Mac) o Ctrl+L (Windows/Linux).
2. Clicca il pulsante Model in fondo all’area di input (mostra il nome del modello corrente accanto a una piccola icona).
3. Disattiva Auto se è attivo.
4. Trova GPT-5.6 Sol nell’elenco e clicca Edit accanto ad esso.
5. Si apre un pannello a destra, dove puoi impostare in modo indipendente finestra di contesto, livello di ragionamento e toggle della velocità.

Scegliere lo sforzo di ragionamento giusto

Selezionare Sol sceglie il modello; lo sforzo di ragionamento decide quanto a fondo pensa su un dato task. Puoi scegliere tra:

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

None e Low sono i più rapidi ed economici, abbastanza buoni per lavoro di autocompletamento o un refactor meccanico dove sai già cosa vuoi. 

High e Extra High impiegano più tempo perché prima ragionano davvero sul problema, e noti la differenza soprattutto quando chiedi all’agente di pianificare qualcosa che attraversa più file o di fare debug di un errore la cui origine non è immediatamente ovvia. 

Max sta sopra Extra High e concede a un singolo agente più tempo per lavorare su un problema difficile. La modalità multi-agente ultra di Sol esiste solo in Codex e nell’API, quindi non la vedrai nel selettore di Cursor.

Una avvertenza se arrivi da GPT-5.5: i livelli non corrispondono. L’indicazione di OpenAI è di iniziare un livello sotto rispetto a ciò che usi di solito su un task familiare e alzarlo solo se serve. L’ho seguito qui sotto, quindi alcuni passaggi girano con uno sforzo inferiore rispetto all’equivalente tutorial su 5.5.

Durante i passaggi pratici qui sotto, ti suggerirò quale livello di ragionamento ha più senso per ciascun task, ma sentiti libero di sperimentare con impostazioni diverse e vedere come cambia l’output.

Scegliere la dimensione della finestra di contesto e la modalità di velocità

Puoi anche scegliere tra una finestra di contesto da 272K e 1M, e attivare la modalità Fast per generare token a circa 1,5x velocità per un costo in crediti di circa 2,5x. Per uno scambio interattivo dove stai aspettando risposte, spesso Fast vale la pena. Per un task più lungo in background che hai passato all’agente mentre fai altro, lasciarlo disattivato va bene.

Configurare Cursor

Configuriamo il progetto in Cursor.

Prerequisiti e configurazione iniziale

È richiesto un piano a pagamento di Cursor (Pro o superiore) per GPT-5.6 Sol e, poiché Sol gira in Max Mode, la tariffazione a consumo deve essere abilitata sul tuo account. Python 3.11+ è l’unica altra dipendenza locale di cui hai bisogno per questo progetto. Se Cursor non è ancora installato, scaricalo da cursor.com, accedi, e poi da un terminale:

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

Il pannello Agent è a destra, e l’esplora file a sinistra non mostra ancora file, esattamente come vuoi partire prima di lasciare che l’agente costruisca la struttura.

Navigare tra le superfici AI di Cursor

Prima di entrare nella build vera e propria, vale la pena conoscere quali sono le tre principali modalità di interazione e quando ha senso usarle, perché usare quella sbagliata crea attrito facilmente evitabile.

Completamento inline è il layer di autocompletamento in background. Mentre scrivi, compaiono suggerimenti in grigio basati su ciò che stai scrivendo e il contesto circostante nel file, e li accetti con Tab. Non lo invochi: compare da solo. È la modalità giusta quando stai scrivendo codice a mano e vuoi che il modello riduca le battute senza interrompere il flusso.

Ask mode è dove puoi far leggere i tuoi file al modello e porre domande senza che apporti modifiche. Pensalo come chiedere a un collega di guardare il codice e dirti cosa vede. È particolarmente utile quando sei in un codebase non familiare, stai cercando di capire perché qualcosa è stato scritto in un certo modo oppure stai ragionando su un approccio prima di impegnarti.

Agent mode è ciò che guida tutto questo tutorial. In una sessione agente, il modello modifica file, esegue comandi del terminale, installa pacchetti, esegue la suite di test, legge l’output e torna sui fallimenti, tutto in un unico thread continuo. È la modalità in cui delega un task piuttosto che fare una domanda, e la qualità di ciò che ottieni scala direttamente con quanto contesto gli dai all’inizio. Puoi vedere il selettore di Agent mode in basso a sinistra del pannello nello screenshot sopra.

Stabilire linee guida specifiche di progetto con AGENTS.md

Questo file lo scrivi tu, quindi niente modello per ora. Passa prima a High, dato che il prossimo prompt è quando l’agente lo legge. La maggior parte delle sessioni agente deraglia non perché il modello sbagli, ma perché ignorava qualcosa di specifico del progetto e ha tirato a indovinare: il tuo framework, le tue convenzioni di naming, quali file sono off-limits, come verificare le modifiche.

È per questo che serve AGENTS.md: un README per l’agente, dove annoti ciò che è ovvio per te ma invisibile al modello. AGENTS.md è nato come iniziativa di OpenAI nel 2025 ed è ora lo standard cross-tool per i file di istruzioni agli agenti (parte della Agentic AI Foundation della Linux Foundation, insieme all’MCP di Anthropic), quindi vale la pena impararlo una volta e usarlo ovunque.

Crea un file chiamato AGENTS.md alla radice del progetto con quanto segue per impostare stack di strumenti, convenzioni di codice e confini del progetto:

# 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.

La sezione dei confini è quella che più spesso si salta, ed è anche la più importante. Senza di essa, gli agenti a volte decidono di “aiutare” riorganizzando o ripulendo cose che non avevi chiesto di toccare. Dire al modello cosa è off-limits è utile tanto quanto dirgli cosa fare.

AGENTS.md è lo standard cross-tool, ma se vuoi l’equivalente nativo di Cursor che fa lo stesso lavoro tramite file .mdc con ambito, il nostro tutorial Cursor Rules illustra come costruirne un set per un progetto web Python.

Costruire una Budget Tracker API con GPT-5.5

Il progetto è una REST API per tracciare voci di budget personali. Puoi creare voci, elencarle con filtro opzionale per categoria, eliminarle e ottenere un riepilogo mensile della spesa. 

È abbastanza semplice da seguire senza perdersi nella logica di dominio, ma l’implementazione coinvolge un livello database, validazione dell’input, modelli di risposta tipizzati e diversi route handler che lavorano insieme: abbastanza per mostrare cosa fa davvero l’agente in una sessione reale multi-file.

Step 1: Impostare l’impalcatura del progetto

Apri il pannello dell’agente e imposta lo sforzo di ragionamento su High prima di inviare qualsiasi cosa. Il piano che l’agente produce prima di scrivere codice è utile quanto il ragionamento che c’è dietro, e una risposta superficiale a questo stadio significa decisioni strutturali che dovrai sbrogliare più tardi. Procedi inviando questo come primo 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.

Vale la pena mantenere quella riga finale in tutti i prompt non banali per l’agente. Chiedere il piano prima dell’esecuzione ti costa forse 15 secondi di lettura, ma ti permette di intercettare decisioni strutturali prima che si propaghino su una dozzina di file. 

GPT-5.6 Sol a High produce piani abbastanza specifici da essere utili davvero, non riassunti vaghi, e rivedere ora la struttura è molto più veloce che riorganizzare dopo.

L’agente propone il layout del progetto e attende approvazione prima di scrivere un singolo file.

Una volta che rispondi con qualcosa tipo "Sembra a posto, vai pure", l’agente inizia a costruire. Puoi vedere l’albero dei file a sinistra popolarsi in tempo reale mentre crea i file, mentre il terminale in basso mostra uv che installa i pacchetti.

L’agente ha creato un pyproject.toml come parte dell’impalcatura, con il contenuto del file mostrato come nuova aggiunta.

Dopo il completamento dell’impalcatura, prenditi un minuto per aprire app/models.py e app/database.py prima di proseguire. Conferma che il modello BudgetEntry abbia almeno i campi id, amount, description, category e date, e che database.py imposti il motore SQLite async senza nulla di insolito. 

Se qualcosa non ti convince, dillo nel prossimo messaggio invece di continuare. Le correzioni a questo stadio costano poco; dopo che venti file sono stati modificati, no.

Step 2: Implementare gli endpoint core

Mantieni lo sforzo su High, o prova prima Medium, dato che Sol a Medium gestisce lavoro coordinato su più file che avrebbe richiesto High su GPT-5.5. Invia il prompt di implementazione:

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.

L’agente tocca models.py, database.py, routers/entries.py e main.py in un unico passaggio coordinato. Man mano che finisce ogni file, Cursor mostra il nuovo contenuto evidenziato nell’editor così puoi rivederlo prima di accettare. Vedrai i controlli Undo/Keep in fondo a ciascun file modificato.

Lo screenshot mostra il router entries.py dopo l’implementazione dell’agente, insieme alla conferma che ha avviato il server e che l’endpoint /docs è stato caricato correttamente. 

Una volta accettata l’implementazione e con il server in esecuzione, apri http://localhost:8000/docs nel browser per confermare che tutto sia collegato correttamente.

La documentazione auto-generata di FastAPI su /docs, con tutti e tre gli endpoint registrati correttamente. 

Step 3: Aggiungere la validazione della categoria

Per questo terzo step, puoi abbassare il ragionamento del modello a Low o Medium. Aggiungere un enum e due test è sufficientemente auto-contenuto e prevedibile da non richiedere cicli extra di deliberazione.

Attualmente, l’API accetta qualsiasi stringa come categoria, il che significa che finirai con dati incoerenti abbastanza in fretta. Sistemiamo così:

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.

L’agente aggiungerà un enum delle categorie in models.py e aggiornerà il modello Pydantic per usarlo. Poiché Pydantic valida automaticamente contro l’enum, le categorie non valide vengono rifiutate prima ancora che il route handler venga eseguito.

Dovrebbe scrivere due test a fianco: uno che conferma che una categoria valida viene salvata correttamente, un altro che conferma che una non valida restituisce un 422.

Usare il riferimento @

Dopo aver accettato quelle modifiche, prova la funzione di contesto @ di Cursor per porre una rapida domanda di verifica:

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

Digitare @ nel pannello dell’agente apre un selettore di file e, una volta selezionato app/models.py, il contenuto di quel file viene inserito direttamente nel prompt senza che l’agente debba cercarlo o fare assunzioni sul percorso.

Step 4: Costruire l’endpoint del riepilogo mensile

Torna su High qui. La query di aggregazione richiede che l’agente ragioni insieme su filtraggio, raggruppamento e design del modello di risposta, e sbagliarne uno solo significa toccare di nuovo tutti e tre i file. Con il CRUD di base funzionante, aggiungi l’endpoint di riepilogo:

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.

Questo è un task database più interessante perché richiede una query filtrata con aggregazione piuttosto che un semplice select-all. Osserva come l’agente struttura la query in database.py; dovrebbe usare l’interfaccia di query di SQLModel e non SQL grezzo, e il risultato dovrebbe mappare pulitamente sul modello di risposta definito in models.py.

Dopo aver accettato le modifiche, scrivi tu un test per questo endpoint in test_entries.py. Crea due voci in un mese specifico, chiama l’endpoint di riepilogo per quel mese e verifica che i totali corrispondano. Scriverlo a mano invece di chiederlo all’agente è un buon modo per familiarizzare con la struttura del test client e delle fixture.

Il file test_entries.py mostra i test di validazione della categoria scritti dall’agente accanto alla funzione test_monthly_summary scritta manualmente. 

Step 5: Eseguire il loop di validazione

Low o Medium vanno bene qui: eseguire test e sistemare problemi di lint è lavoro reattivo, l’agente legge l’output di errore e applica fix mirati piuttosto che prendere decisioni architetturali. Passa i test all’agente:

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.

Osserva il pannello dell’agente mentre trasmette l’output di pytest. 

Se qualcosa fallisce, l’agente legge il traceback, identifica quale file ha introdotto il problema e applica la correzione, tutto nella stessa sessione. Non devi copiare-incollare l’errore in un nuovo messaggio; l’intero loop di debug e fix avviene in un unico thread continuo.

Lo screenshot mostra l’agente che riporta dopo il loop di validazione completo. In questo caso, il check di ruff ha incontrato un problema di risoluzione dell’interprete causato da un disallineamento pyenv/.python-version sulla macchina locale, non un problema di codice. 

Vale la pena notare cosa è successo: l’agente ha incontrato un problema di ambiente non correlato al codice scritto, ne ha ragionato la causa e ha trovato una soluzione alternativa senza essere sollecitato. Questo tipo di problem-solving contestuale attraverso errori degli strumenti è esattamente dove GPT-5.6 Sol stacca i modelli precedenti.

Vale anche la pena includere "non modificare le asserzioni dei test per farle passare" in ogni prompt di validazione che scrivi. Senza quella istruzione, occasionalmente gli agenti prendono la via più facile e indeboliscono ciò che un test verifica anziché correggere il comportamento reale.

Step 6: Passaggio di code review

Imposta di nuovo il ragionamento su High prima di inviare questo, o su Extra High/Max se vuoi che Sol approfondisca i casi limite che un singolo passaggio High potrebbe sorvolare. A questo step, un ragionamento superficiale crea un falso senso di sicurezza; vuoi che il modello lavori davvero su tutte le potenziali issue, non solo che faccia pattern-matching su quelle più ovvie. 

Prima di considerare il progetto finito, usa l’agente per una 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.

L’agente ha rilevato che DELETE /api/v1/entries/{entry_id} restituisce correttamente i codici 204 e 404 (con riferimenti file:riga), che le route GET si affidano ai corretti default 200 e ha confermato che nessun input utente raggiunge il database al di fuori dell’ORM.

Dopo aver rivisto l’elenco, invia il follow-up per applicare le correzioni:

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.

Step 7: README e workflow CI

Due ritocchi finali per chiudere il progetto a dovere. Puoi abbassare il ragionamento del modello a Low per entrambi. La struttura del README è prevedibile, e lo YAML della CI è sostanzialmente boilerplate, quindi non c’è nulla su cui ragionare davvero, e pagare per un ragionamento alto qui è solo spreco di crediti.

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

E poi:

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

Dopo tutti e sette gli step, la struttura del progetto è così:

Considerazioni finali

Quello che abbiamo costruito qui è una piccola API, ma il workflow scala a qualsiasi cosa. 

Metti in piedi AGENTS.md prima che l’agente tocchi un singolo file. Chiedi il piano prima di eseguire su qualsiasi cosa non banale. Scandisci i prompt, così hai checkpoint naturali invece di un unico gigantesco diff da rivedere tutto insieme. Usa @filename quando vuoi chiedere qualcosa di mirato su un file specifico. E fai un passaggio di review prima di considerare un task concluso, perché quasi sempre troverai qualcosa.

GPT-5.6 Sol in Cursor è sensibilmente migliore delle combinazioni precedenti nel rimanere sul compito attraverso sessioni lunghe, cogliere incoerenze tra file e sapere quando fermarsi e chiedere conferma invece di andare avanti a testa bassa su qualcosa di distruttivo. Ma il modello è solo una parte del quadro. Il contesto che gli dai all’inizio, i loop di validazione che esegui e il passaggio di review alla fine: è lì che sta il vero miglioramento della qualità dell’output.

Una buona regola empirica sui livelli di ragionamento: usa High per decisioni di architettura, coordinamento multi-file e debug di qualcosa di non ovvio; usa Medium o Low per documentazione, boilerplate e modifiche a singolo file dove stai solo chiedendo al modello di battere alla tastiera. Considera Extra High o Max per code review e dove gli errori costano più di una esecuzione approfondita dell’agente.