Cursor Agent-modus-tutorial: Een REST-API bouwen met GPT-5.6 Sol

Wat is Cursor?

Cursor begon als VS Code met AI-functies erin genaaid, en aan de oppervlakte ziet het er nog steeds zo uit. De editor, de bestandsboom, de terminal, de extensies, allemaal vertrouwd. 

Wat eronder opnieuw is opgebouwd, is de aanname dat de AI niet alleen aan de zijlijn vragen beantwoordt, maar daadwerkelijk naast je werkt. Daarom heb je agent-modus, codebase-indexering, een modelkiezer waarmee je tijdens een sessie tussen frontier-modellen kunt wisselen, en inline-aanvullingen die je volgende stap voorspellen op basis van de volledige context van wat je hebt gedaan.

Als je Cursor’s nieuwste functies verder wilt verkennen, raad ik onze tutorials over Cursor Automations en Cursor SDK aan.

Wat is GPT-5.6?

GPT-5.6 is de nieuwste modelgeneratie van OpenAI, en het is niet één model maar drie: Sol, Terra en Luna. Die namen zijn drie aparte capaciteitsniveaus en vervangen het oude label "Instant".

Hier is de familie in het kort:

• Sol is het vlaggenschip en de sterkste van de drie. Het is de enige laag die het nieuwe max-reasoning level en de ultra-modus ontgrendelt, en hier zijn de grootste winstpunten op coderen, biologie en cybersecurity.

• Terra is de dagelijkse standaard. OpenAI positioneert het als concurrerend met GPT-5.5 voor ongeveer de helft van de prijs.

• Luna is de snelle, goedkope laag voor hoog volume of latency-gevoelig werk, en sterker dan het prijskaartje doet vermoeden.

Voor een coding-walkthrough is Sol de laag die telt, dus die gebruiken we hier. Twee instellingen op Sol zijn nieuw, en het is de moeite waard te weten welke je echt gebruikt. max is een reasoning-inspanning boven xhigh die één agent langer aan één moeilijk probleem laat werken, en het is het hoogste niveau dat je in Cursor instelt. ultra, dat werk splitst over parallelle subagents, haalt OpenAI’s beste benchmarkcijfers (91,9% op Terminal-Bench 2.1) maar draait alleen in Codex en de API, dus je vindt het niet in de Cursor-kiezer.

Voor de volledige benchmarktabel en de prijsstelling per laag, bekijk onze GPT-5.6 Sol-, Terra- en Luna-gids.

GPT-5.6 Sol openen en configureren in Cursor

GPT-5.6 Sol is beschikbaar in de modelkiezer van Cursor, en er is één ding dat je vooraf moet weten: net als Cursor’s andere recente frontier-modellen draait Sol alleen in Cursor’s Max-modus. Dat betekent dat het het volledige contextvenster en alle tools gebruikt, en per gebruik wordt gefactureerd in plaats van per request. Houd dus je tokenverbruik in de gaten tijdens lange runs.

Zo selecteer je het model:

1. Open het agentpaneel met Cmd+L (Mac) of Ctrl+L (Windows/Linux).
2. Klik op de knop Model onderaan het invoerveld (de huidige modelnaam staat ernaast met een klein icoon).
3. Zet Auto uit als het aan staat.
4. Zoek GPT-5.6 Sol in de lijst en klik op Bewerken ernaast.
5. Er opent rechts een paneel waar je het contextvenster, het redeneerniveau en de snelschakelaar onafhankelijk kunt instellen.

Het juiste redeneerniveau kiezen

Sol selecteren kiest het model; de redeneerinspanning bepaalt hoe diep het nadenkt over een taak. Je kunt kiezen uit:

• Geen
• Laag
• Middel
• Hoog
• Extra hoog
• Max

Geen en Laag zijn het snelst en goedkoopst, goed genoeg voor autocomplete-werk of een mechanische refactor waarbij je in feite al weet wat je wilt. 

Hoog en Extra hoog duren langer omdat ze eerst echt het probleem doordenken. Dat merk je vooral als je de agent vraagt iets te plannen dat meerdere bestanden raakt, of een fout te debuggen waarvan de oorzaak niet meteen duidelijk is. 

Max zit boven Extra hoog en geeft één agent de meeste tijd om aan een moeilijk probleem te werken. Sol’s ultra-multi-agentmodus bestaat alleen in Codex en de API, dus je ziet die niet in Cursor’s kiezer.

Eén waarschuwing als je van GPT-5.5 komt: de niveaus komen niet overeen. OpenAI’s eigen advies is om bij een bekende taak één niveau lager te beginnen dan je gewend bent en het pas op te schroeven als het resultaat daarom vraagt. Ik heb dat hieronder gevolgd, dus een paar stappen draaien op een lager niveau dan het equivalente 5.5-tutorial zou doen.

Door de hands-on stappen hieronder heen zal ik voorstellen welk redeneerniveau het meest logisch is per taak, maar voel je vrij om te experimenteren met verschillende instellingen en te zien hoe de output verandert.

Contextvenstergrootte en snelheidsmodus kiezen

Je kunt ook kiezen tussen een 272K- en 1M-contextvenster, en Snel aanzetten om tokens met ongeveer 1,5x snelheid te genereren voor circa 2,5x de kredietkosten. Voor interactieve back-and-forth waarbij je op reacties wacht, is Snel vaak de moeite waard. Voor een langere achtergrondtaak waarbij je iets uitbesteedt en ondertussen andere dingen doet, is het prima om het uit te laten.

Cursor instellen

Laten we het project in Cursor opzetten.

Vereisten en initiële configuratie

Een betaald Cursor-abonnement (Pro of hoger) is vereist voor GPT-5.6 Sol, en omdat Sol in Max-modus draait, moet prijsstelling op basis van gebruik op je account zijn ingeschakeld. Python 3.11+ is de enige andere lokale afhankelijkheid die je voor dit project nodig hebt. Als Cursor nog niet is geïnstalleerd, haal het op via cursor.com, meld je aan en voer dan vanuit een terminal het volgende uit:

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

Het Agentpaneel staat rechts, en de verkenner links toont nog geen bestanden—precies waar je wilt beginnen voordat je de agent de structuur laat opzetten.

Navigeren door de AI-oppervlakken van Cursor

Voordat we aan de daadwerkelijke build beginnen, is het handig om te weten wat de drie belangrijkste interactiemodi zijn en wanneer welke zinvol is, want de verkeerde gebruiken zorgt voor frictie die je makkelijk kunt vermijden.

Inline-aanvulling is de achtergrond-autocomplete-laag. Terwijl je typt, verschijnen grijze suggesties op basis van wat je schrijft en de omringende context in het bestand, en je accepteert ze met Tab. Je roept het niet aan; het verschijnt gewoon. Dit is de juiste modus wanneer je met de hand code schrijft en het model toetsaanslagen wil laten besparen zonder je flow te onderbreken.

Ask-modus is waar je het model je bestanden kunt laten lezen en vragen kunt laten beantwoorden zonder dat het iets wijzigt. Zie het als een collega vragen naar de code te kijken en te vertellen wat die ziet. Dit is vooral nuttig in een onbekende codebase, als je wilt begrijpen waarom iets op een bepaalde manier is geschreven, of gewoon een aanpak wilt doordenken voordat je je eraan commit.

Agent-modus drijft deze hele tutorial. In een agentsessie bewerkt het model bestanden, draait terminalcommando’s, installeert pakketten, voert je testsuite uit, leest de output en loopt terug bij fouten—alles binnen één doorlopende thread. Dit is de modus waarin je een taak overdraagt in plaats van ernaar te vragen, en de kwaliteit schaalt recht mee met hoeveel context je vooraf geeft. Je ziet de agent-modusselectie linksonder in het paneel in de screenshot hierboven.

Projectspecifieke richtlijnen vastleggen met AGENTS.md

Dit bestand schrijf je zelf, dus nog geen model. Schakel eerst naar Hoog, want bij de volgende prompt leest de agent het. De meeste agentsessies lopen mis, niet omdat het model een fout maakt, maar omdat het iets projectspecifieks niet wist en gokte: je framework, je naamgevingsconventies, welke bestanden off-limits zijn, hoe je wijzigingen verifieert.

Daar is AGENTS.md voor: een README voor de agent, waarin je opschrijft wat voor jou vanzelfsprekend is maar voor het model onzichtbaar. AGENTS.md begon als een OpenAI-initiatief in 2025 en is nu de tooloverstijgende standaard voor agent-instructiebestanden (onder deel van de Agentic AI Foundation van de Linux Foundation, naast Anthropic’s MCP), dus het is de moeite waard dit één keer te leren en overal te gebruiken.

Maak een bestand genaamd AGENTS.md in de projectroot met het volgende om je toolstack, codeerconventies en grenzen vast te leggen:

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

De sectie met grenzen is wat mensen het vaakst overslaan, en tegelijk de belangrijkste. Zonder dat besluiten agents soms om "te helpen" door dingen te herorganiseren of op te schonen waar je niet om vroeg. Het model vertellen wat off-limits is, is net zo nuttig als zeggen wat het wél moet doen.

AGENTS.md is de tooloverstijgende standaard, maar als je de Cursor-native tegenhanger wilt die hetzelfde doet via gescope-de .mdc-bestanden, dan loopt onze Cursor Rules-tutorial door het opzetten van een set voor een Python-webproject.

Een Budget Tracker-API bouwen met GPT-5.5

Het project is een REST-API voor het bijhouden van persoonlijke budgetposten. Je kunt posten aanmaken, ze lijstten met optionele categoriefilter, ze verwijderen en een maandelijkse uitgavensamenvatting ophalen. 

Het is eenvoudig genoeg om te volgen zonder te verdwalen in domeinlogica, maar de implementatie omvat een databaselaag, invoervalidatie, getypeerde responsemodellen en meerdere routehandlers die samenwerken—genoeg om te laten zien wat de agent daadwerkelijk doet in een echte sessie met meerdere bestanden.

Stap 1: Het projectstructuur skelet opzetten

Open het agentpaneel en zet de redeneerinspanning op Hoog voordat je iets verstuurt. Het plan dat de agent oplevert vóór er ook maar één regel code is geschreven, is alleen zo nuttig als het denkwerk erachter; een oppervlakkig antwoord op dit punt betekent structurele keuzes die je later moet ontwarren. Ga verder door dit als je eerste prompt te sturen:

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.

Die laatste regel is de moeite waard om in al je niet-triviale agentprompts te houden. Om het plan vragen vóór uitvoering kost je misschien 15 seconden leestijd, maar laat je structurele keuzes vangen voordat ze zich over een dozijn bestanden hebben verspreid. 

GPT-5.6 Sol op Hoog redeneert tot plannen die specifiek genoeg zijn om nuttig te zijn, geen vage samenvattingen, en de structuur nu reviewen is veel sneller dan later reorganiseren.

De agent stelt de projectindeling voor en wacht op goedkeuring voordat er ook maar één bestand wordt geschreven.

Zodra je reageert met iets als "Ziet er goed uit, ga je gang", begint de agent te bouwen. Je ziet de bestandsboom links in realtime gevuld worden terwijl er bestanden worden gemaakt, terwijl de terminal onderaan laat zien dat uv pakketten installeert.

De agent heeft een pyproject.toml aangemaakt als onderdeel van het skelet, met de inhoud van het bestand als nieuwe toevoeging weergegeven.

Na het opzetten, neem even de tijd om app/models.py en app/database.py te openen voordat je doorgaat. Bevestig dat het BudgetEntry-model minstens de volgende velden heeft: id, amount, description, category en date, en dat database.py de async SQLite-engine zonder iets geks opzet. 

Als iets niet klopt, zeg het in het volgende bericht in plaats van door te gaan. Correcties op dit punt zijn goedkoop; na twintig gewijzigde bestanden niet meer.

Stap 2: De kernendpoints implementeren

Houd de inspanning op Hoog, of probeer eerst Middel, aangezien Sol op Middel gecoördineerd werk over meerdere bestanden aankan dat op GPT-5.5 Hoog nodig had. Stuur de implementatieprompt:

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.

De agent raakt in één gecoördineerde pass models.py, database.py, routers/entries.py en main.py aan. Terwijl elk bestand wordt afgerond, toont Cursor de nieuwe inhoud gemarkeerd in de editor zodat je die kunt reviewen vóór je accepteert. Onderaan elk gewijzigd bestand zie je de Undo/Keep-knoppen.

De screenshot toont de entries.py-router nadat de agent die heeft geïmplementeerd, samen met de bevestiging van de agent dat de server is gestart en dat het /docs-endpoint correct laadde. 

Zodra de implementatie is geaccepteerd en de server draait, open je http://localhost:8000/docs in je browser om te bevestigen dat alles correct is aangesloten.

De door FastAPI automatisch gegenereerde docs op /docs, waarop alle drie de endpoints correct zijn geregistreerd. 

Stap 3: Categorievalidatie toevoegen

Voor deze derde stap kun je het redeneerniveau verlagen naar Laag of Middel. Het toevoegen van een enum en twee tests is afgebakend en voorspelbaar genoeg dat je geen extra denkrondes hoeft te betalen.

Momenteel accepteert de API elke string als categorie, wat al snel leidt tot inconsistente data. Laten we dat fixen:

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.

De agent zal een categorie-enum toevoegen aan models.py en het Pydantic-model bijwerken zodat het die gebruikt. Omdat Pydantic automatisch tegen de enum valideert, worden ongeldige categorieën afgewezen vóór de routehandler überhaupt draait.

Er zouden twee tests naast elkaar moeten worden geschreven: één die bevestigt dat een geldige categorie correct wordt opgeslagen, en een andere die bevestigt dat een ongeldige een 422 teruggeeft.

De @-referentie gebruiken

Na het accepteren van die wijzigingen, probeer de @-contextfunctie van Cursor om een snelle verificatievraag te stellen:

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

Het typen van @ in het agentpaneel opent een bestandskiezer, en zodra je app/models.py selecteert, wordt de inhoud van dat bestand direct in de prompt getrokken zonder dat de agent hoeft te zoeken of aannames over het pad hoeft te doen.

Stap 4: Het maandelijkse samenvattingsendpoint bouwen

Schakel hier terug naar Hoog. De aggregatiequery vereist dat de agent filteren, groeperen en het ontwerp van het responsemodel samen overweegt, en als één daarvan misgaat, moeten alle drie de bestanden opnieuw worden aangeraakt. Met de kern-CRUD werkend, voeg je het samenvattingsendpoint toe:

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.

Dit is een interessantere databasetaak omdat het een gefilterde query met aggregatie vereist in plaats van een simpele select-all. Let op hoe de agent de query in database.py structureert; het zou de query-interface van SQLModel moeten gebruiken in plaats van rauwe SQL, en het resultaat moet netjes aansluiten op het responsemodel dat in models.py is gedefinieerd.

Schrijf na het accepteren van de wijzigingen zelf één test voor dit endpoint in test_entries.py. Maak twee entries in een specifieke maand, roep het samenvattingsendpoint voor die maand aan en controleer of de totalen kloppen. Dit handmatig schrijven in plaats van de agent vragen is een goede manier om vertrouwd te raken met hoe de testclient en fixtures zijn opgezet.

Het bestand test_entries.py toont de door de agent geschreven categorievalidatietests naast de handmatig geschreven functie test_monthly_summary. 

Stap 5: De validatieloop draaien

Laag of Middel redeneren werkt hier prima; tests draaien en lintproblemen oplossen is reactief werk, de agent leest foutoutput en past gerichte fixes toe in plaats van echte architectuurkeuzes te maken. Geef het testen terug aan de agent:

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.

Kijk in het agentpaneel hoe de pytest-output wordt gestreamd. 

Als iets faalt, leest de agent de traceback, bepaalt welk bestand het probleem introduceerde en past de fix toe—alles binnen dezelfde sessie. Je hoeft de fout niet te kopiëren en in een nieuw bericht te plakken; de hele debug- en fixloop gebeurt binnen één doorlopende thread.

De screenshot toont de agent die rapporteert na de volledige validatieloop. In dit geval veroorzaakte de ruff-check een interpreter-resolutieprobleem door een mismatch van pyenv/.python-version op de lokale machine, geen codeprobleem. 

Het is de moeite waard te benoemen wat hier gebeurde: de agent stuitte op een omgevingsprobleem dat losstond van de code die we schreven, redeneerde over de oorzaak en vond zonder prompt een workaround. Dat soort contextueel probleemoplossen over toolstoringen heen is precies waar GPT-5.6 Sol voorloopt op eerdere modellen.

Het is ook handig om "wijzig geen testasserties om ze te laten slagen" in elke validatieprompt op te nemen. Zonder die instructie kiezen agents soms voor de weg van de minste weerstand en verzwakken ze wat een test controleert in plaats van het daadwerkelijke gedrag te fixen.

Stap 6: Code review-pass

Zet het redeneerniveau terug op Hoog voordat je deze verstuurt, of Extra hoog/Max als je wilt dat Sol zich vastbijt in randgevallen die één Hoog-pass kan overslaan. Op dit punt geeft oppervlakkig redeneren een vals gevoel van veiligheid; je wilt dat het model echt alle potentiële issues doorloopt, niet alleen patternmatchen op de meest voor de hand liggende.

Gebruik de agent voor een review voordat je het project afrondt:

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.

De agent vond dat DELETE /api/v1/entries/{entry_id} correct de codes 204 en 404 retourneert (met bestand:regel-referenties), dat GET-routes vertrouwen op correcte 200-defaults, en bevestigde dat geen gebruikersinvoer de database bereikt buiten de ORM om.

Stuur na het reviewen van de lijst de follow-up om de fixes toe te passen:

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.

Stap 7: README en CI-workflow

Twee laatste puntjes om het project netjes af te ronden. Je kunt het redeneerniveau voor beide op Laag zetten. De structuur van de README is voorspelbaar en de CI-YAML is in wezen boilerplate, dus er valt niets te beredeneren en betalen voor hoog redeneren is hier zonde van je credits.

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

En daarna:

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

Na alle zeven stappen ziet de projectstructuur er zo uit:

Tot slot

Wat we hier hebben gebouwd is een kleine API, maar de workflow schaalt naar alles. 

Zorg dat AGENTS.md klaarstaat voordat de agent één bestand aanraakt. Vraag om het plan vóór uitvoering bij alles wat niet triviaal is. Stuur je prompts gefaseerd, zodat je natuurlijke controlemomenten hebt in plaats van één gigantische diff om in één keer te reviewen. Gebruik @bestandsnaam wanneer je iets gerichts wilt vragen over een specifiek bestand. En draai een review-pass voordat je iets als klaar beschouwt, want je vangt bijna altijd nog iets.

GPT-5.6 Sol in Cursor is merkbaar beter dan eerdere combinaties in op taak blijven tijdens lange sessies, kruisbestandsinconsistenties vangen en weten wanneer te pauzeren en in te checken in plaats van destructief door te denderen. Maar het model is slechts een deel van het verhaal. De context die je vooraf geeft, de validatielussen die je draait en de review-pass aan het eind—daar komt de echte kwaliteitswinst vandaan.

Een goede vuistregel voor redeneerniveaus: gebruik Hoog voor architectuurkeuzes, coördinatie over meerdere bestanden en het debuggen van iets niet voor de hand liggends; gebruik Middel of Laag voor documentatie, boilerplate en single-file-edits waarbij je het model eigenlijk alleen laat typen. Overweeg Extra hoog of Max voor code reviews en waar fouten kostbaarder zijn dan een grondige agenrun.