Cursor-Agent-Modus Tutorial: Eine REST-API mit GPT-5.6 Sol bauen

Was ist Cursor?

Cursor startete als VS Code mit eingebauten KI-Funktionen und wirkt an der Oberfläche noch immer so. Editor, Dateibaum, Terminal, Erweiterungen – alles vertraut. 

Neu gedacht wurde darunter die Annahme, dass die KI nicht nur nebenbei Fragen beantwortet, sondern aktiv mit dir arbeitet. Deshalb gibt es den Agent-Modus, Codebase-Indexierung, einen Modellwähler zum Wechseln zwischen Spitzenmodellen mitten in der Session und Inline-Vervollständigungen, die deinen nächsten Schritt aus dem vollen Kontext deiner Arbeit ableiten.

Wenn du Cursors neueste Features weiter erkunden willst, lies unsere Tutorials zu Cursor Automations und Cursor SDK.

Was ist GPT-5.6?

GPT-5.6 ist OpenAIs neueste Modellgeneration – nicht ein Modell, sondern drei: Sol, Terra und Luna. Diese Namen stehen für drei klare Fähigkeitsstufen und ersetzen das alte "Instant"-Label.

Kurz zur Familie:

• Sol ist das Flaggschiff und das stärkste der drei. Nur hier gibt es die neue max-Reasoning-Stufe und den ultra-Modus; hier sind die größten Fortschritte bei Coding, Biologie und Cybersicherheit.

• Terra ist der Alltagsstandard. OpenAI positioniert es als konkurrenzfähig zu GPT-5.5 bei etwa halben Kosten.

• Luna ist die schnelle, günstige Stufe für hohes Volumen oder niedrige Latenz – stärker, als der Preis vermuten lässt.

Für diesen Coding-Walkthrough zählt Sol, deshalb nutzen wir es hier. Zwei Sol-Einstellungen sind neu und du solltest wissen, welche du wirklich brauchst. max ist eine Reasoning-Stufe über xhigh, mit der ein einzelner Agent länger an einem harten Problem arbeiten darf – das ist die oberste Stufe, die du in Cursor einstellst. ultra teilt Arbeit auf parallele Subagenten auf, liefert OpenAIs beste Benchmarkzahlen (91,9% auf Terminal-Bench 2.1), läuft aber nur in Codex und der API – du findest es nicht im Cursor-Picker.

Die vollständige Benchmark-Tabelle und die dreistufige Preisübersicht findest du in unserem Leitfaden zu GPT-5.6 Sol, Terra und Luna.

GPT-5.6 Sol in Cursor aufrufen und konfigurieren

GPT-5.6 Sol ist im Cursor-Model-Picker verfügbar, und eine Sache ist wichtig vorab: Wie andere aktuelle Frontier-Modelle in Cursor läuft Sol ausschließlich im Max Mode. Das heißt, es nutzt das volle Kontextfenster und alle Tools und wird nutzungsbasiert abgerechnet statt pro Anfrage. Behalte bei langen Läufen also deinen Tokenverbrauch im Blick.

So wählst du das Modell aus:

1. Öffne das Agent-Panel mit Cmd+L (Mac) oder Ctrl+L (Windows/Linux).
2. Klicke unten im Eingabefeld auf den Model-Button (zeigt den aktuellen Modellnamen neben einem kleinen Icon).
3. Schalte Auto aus, falls aktiv.
4. Finde GPT-5.6 Sol in der Liste und klicke daneben auf Edit.
5. Rechts öffnet sich ein Panel, in dem du Kontextfenster, Reasoning-Level und Fast-Modus unabhängig voneinander einstellen kannst.

Den richtigen Reasoning-Aufwand wählen

Mit Sol wählst du das Modell; der Reasoning-Aufwand bestimmt, wie gründlich es für eine Aufgabe nachdenkt. Zur Auswahl stehen:

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

None und Low sind am schnellsten und günstigsten – ideal für Autocomplete-Arbeit oder eine mechanische Umstrukturierung, wenn du ohnehin weißt, was du willst. 

High und Extra High dauern länger, weil das Modell das Problem zuerst wirklich durchdenkt. Den Unterschied merkst du vor allem, wenn der Agent etwas planen soll, das mehrere Dateien betrifft, oder wenn du einen Fehler debuggen lässt, dessen Ursache nicht auf der Hand liegt. 

Max liegt oberhalb von Extra High und gibt einem einzelnen Agent am meisten Zeit für ein hartes Problem. Sols ultra-Multi-Agent-Modus existiert nur in Codex und der API, daher taucht er im Cursor-Picker nicht auf.

Ein Hinweis, wenn du von GPT-5.5 kommst: Die Stufen sind nicht direkt vergleichbar. OpenAI empfiehlt, bei bekannten Aufgaben eine Stufe niedriger zu starten und nur hochzuschalten, wenn das Ergebnis es braucht. Ich halte mich unten daran, daher laufen einige Schritte mit geringerem Aufwand als im entsprechenden 5.5-Tutorial.

In den praktischen Schritten unten schlage ich jeweils das sinnvollste Reasoning-Level vor. Experimentiere gern selbst und sieh dir an, wie sich die Ergebnisse verändern.

Kontextfenstergröße und Speed-Modus wählen

Du kannst zwischen einem 272K- und 1M-Kontextfenster wählen und den Fast-Modus aktivieren, um etwa 1,5× schneller zu generieren bei ca. 2,5× Kosten. Bei interaktiver Rückfrage lohnt sich Fast oft. Für längere Hintergrundaufgaben, die du übergibst und währenddessen anderes machst, kannst du es getrost auslassen.

Cursor einrichten

Richten wir das Projekt in Cursor ein.

Voraussetzungen und Initialkonfiguration

Für GPT-5.6 Sol brauchst du einen bezahlten Cursor-Plan (Pro oder höher). Da Sol im Max Mode läuft, muss nutzungsbasierte Abrechnung in deinem Account aktiviert sein. Python 3.11+ ist die einzige weitere lokale Abhängigkeit für dieses Projekt. Wenn Cursor noch nicht installiert ist, hol es dir auf cursor.com, melde dich an und dann im Terminal:

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

Rechts ist das Agent-Panel, links zeigt der Explorer noch keine Dateien – genau so solltest du starten, bevor der Agent die Struktur aufbaut.

Cursors KI-Oberflächen navigieren

Bevor wir mit dem Build beginnen, lohnt es sich, die drei Haupt-Interaktionsmodi und ihre Einsatzfälle zu kennen. Der falsche Modus sorgt sonst für unnötige Reibung.

Inline-Completion ist die Autovervollständigung im Hintergrund. Während du tippst, erscheinen ausgegraute Vorschläge basierend auf deinem Text und dem Kontext der Datei; du akzeptierst sie mit Tab. Du rufst das nicht aktiv auf – es ist einfach da. Ideal, wenn du per Hand schreibst und die KI Tipparbeit reduziert, ohne deinen Flow zu stören.

Ask-Mode liest deine Dateien und beantwortet Fragen, ohne etwas zu ändern. Denk an „Kollege schaut drüber und gibt Feedback“. Besonders nützlich in unbekanntem Code, wenn du Motive verstehen oder einen Ansatz durchdenken willst, bevor du dich festlegst.

Agent-Mode treibt dieses Tutorial. In einer Agent-Session bearbeitet das Modell Dateien, führt Terminal-Kommandos aus, installiert Pakete, startet deine Tests, liest die Ausgaben und iteriert bei Fehlern – alles in einem durchgehenden Thread. Hier übergibst du Aufgaben statt nur Fragen zu stellen, und die Qualität skaliert direkt mit dem Kontext, den du vorab gibst. Den Agent-Mode-Schalter siehst du unten links im Panel im obigen Screenshot.

Projektspezifische Leitplanken mit AGENTS.md festlegen

Diese Datei schreibst du selbst, also noch kein Modell. Stelle zuerst auf High, denn die nächste Eingabe liest der Agent. Die meisten Agent-Sessions laufen schief, nicht weil das Modell „falsch“ lag, sondern weil es Projektdetails nicht kannte und raten musste: Framework, Namenskonventionen, Tabuzonen, wie Änderungen zu verifizieren sind.

Dafür ist AGENTS.md da: ein README für den Agent, in dem du festhältst, was für dich selbstverständlich ist, für das Modell aber unsichtbar. AGENTS.md begann 2025 als OpenAI-Initiative und ist heute der toolübergreifende Standard für Agent-Instruktionsdateien (Teil der Agentic AI Foundation der Linux Foundation, neben Anthropics MCP), daher: Einmal lernen, überall nutzen.

Lege im Projekt-Root eine Datei AGENTS.md an mit Folgendem, um Tool-Stack, Coding-Konventionen und Grenzen festzulegen:

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

Der Abschnitt „Boundaries“ wird am häufigsten weggelassen und ist zugleich der wichtigste. Ohne ihn „hilft“ der Agent gelegentlich mit Aufräumen oder Umstrukturieren, die du nicht angefragt hast. Zu sagen, was tabu ist, ist genauso wichtig wie der Auftrag selbst.

AGENTS.md ist der Standard über Tools hinweg. Wenn du die Cursor-native Entsprechung mit fokussierten .mdc-Dateien willst, zeigt unser Cursor Rules-Tutorial, wie du ein Set für ein Python-Webprojekt aufbaust.

Eine Budget-Tracker-API mit GPT-5.5 bauen

Das Projekt ist eine REST-API zum Verwalten persönlicher Budget-Einträge. Du kannst Einträge anlegen, mit optionalem Kategorie-Filter auflisten, löschen und eine monatliche Ausgabenzusammenfassung abrufen. 

Einfach genug, um nicht in Domänenlogik zu versinken – aber mit Datenbankschicht, Eingabevalidierung, typisierten Response-Modellen und mehreren zusammenspielenden Routen-Handlern. Genau richtig, um zu zeigen, was der Agent in einer echten Multi-File-Session leistet.

Schritt 1: Projektstruktur erstellen

Öffne das Agent-Panel und setze den Reasoning-Aufwand auf High, bevor du etwas sendest. Der Plan, den der Agent vor dem ersten Code schreibt, ist nur so gut wie das zugrundeliegende Denken. Eine flache Antwort hier führt zu Struktur-Entscheidungen, die du später mühsam entwirren musst. Sende dann diese erste Eingabe:

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 letzte Zeile solltest du in allen nicht-trivialen Agent-Prompts beibehalten. Erst den Plan zeigen zu lassen, kostet dich vielleicht 15 Sekunden Lesezeit, fängt aber Strukturentscheidungen ab, bevor sie sich über ein Dutzend Dateien verteilen. 

GPT-5.6 Sol liefert bei High Reasoning Pläne, die konkret genug sind, um wirklich zu helfen – keine vagen Zusammenfassungen. Jetzt zu prüfen ist viel schneller, als später umzubauen.

Der Agent schlägt das Layout vor und wartet vor dem ersten Schreibzugriff auf deine Freigabe.

Sobald du mit „Sieht gut aus, leg los“ antwortest, baut der Agent los. Du siehst links den Dateibaum in Echtzeit wachsen, während unten im Terminal uv Pakete installiert.

Der Agent hat im Scaffold eine pyproject.toml erstellt und den neuen Inhalt im Editor hervorgehoben.

Nach dem Scaffold nimm dir eine Minute und öffne app/models.py sowie app/database.py. Prüfe, ob das BudgetEntry-Modell mindestens die Felder id, amount, description, category und date hat und ob database.py den async-SQLite-Engine ohne Besonderheiten aufsetzt. 

Wenn etwas komisch aussieht, sag es in der nächsten Nachricht – nicht weitermachen. Korrekturen sind jetzt billig; nach zwanzig geänderten Dateien nicht mehr.

Schritt 2: Kern-Endpunkte implementieren

Bleib bei High oder probiere Medium – Sol schafft bei Medium koordinierte Multi-File-Arbeit, für die GPT-5.5 High brauchte. Sende den Implementierungs-Prompt:

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.

Der Agent fasst models.py, database.py, routers/entries.py und main.py in einem koordinierten Durchlauf an. Während er jede Datei fertigstellt, zeigt Cursor die neuen Inhalte hervorgehoben, damit du vor dem Übernehmen prüfen kannst. Unten in jeder geänderten Datei siehst du Undo/Keep.

Der Screenshot zeigt den Router entries.py nach der Implementierung sowie die Bestätigung des Agents, dass der Server gestartet wurde und /docs korrekt lädt. 

Wenn die Implementierung übernommen ist und der Server läuft, öffne http://localhost:8000/docs im Browser und prüfe, ob alles korrekt verdrahtet ist.

Die von FastAPI generierte Doku unter /docs zeigt alle drei Endpunkte korrekt registriert. 

Schritt 3: Kategorien validieren

Für diesen Schritt kannst du das Reasoning auf Low oder Medium senken. Ein Enum plus zwei Tests ist in sich geschlossen und vorhersehbar – dafür muss das Modell keine zusätzlichen Denkrunden drehen. 

Aktuell akzeptiert die API jeden String als Kategorie – inkonsistente Daten sind vorprogrammiert. Das beheben wir:

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.

Der Agent ergänzt ein Kategorie-Enum in models.py und aktualisiert das Pydantic-Modell, damit es das Enum nutzt. Pydantic validiert automatisch gegen das Enum – ungültige Kategorien werden abgelehnt, bevor der Route-Handler läuft.

Außerdem sollten zwei Tests entstehen: einer, der eine gültige Kategorie erfolgreich speichert, und einer, der bei ungültiger Kategorie einen 422 zurückliefert.

Die @-Referenz nutzen

Nach dem Übernehmen kannst du mit Cursors @-Kontext schnell verifizieren:

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

Beim Tippen von @ öffnet sich ein Dateiauswahldialog. Sobald du app/models.py auswählst, wird der Dateiinhalt direkt in den Prompt gezogen – ganz ohne Suche oder Pfad-Raten.

Schritt 4: Monatsübersicht bauen

Wechsle hier zurück auf High. Die Aggregationsabfrage verlangt zusammenhängendes Denken über Filterung, Gruppierung und Response-Design. Sitzt hier etwas schief, müssen gleich mehrere Dateien erneut angefasst werden. Mit funktionierendem CRUD fügst du den Summary-Endpunkt hinzu:

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.

Das ist die interessantere DB-Aufgabe: gefilterte Abfrage mit Aggregation statt einfachem Select. Achte darauf, wie der Agent die Abfrage in database.py strukturiert – idealerweise mit SQLModel-Query-Interface statt Raw SQL – und wie das Ergebnis sauber in das in models.py definierte Response-Modell passt.

Nach dem Übernehmen schreibst du selbst einen Test für diesen Endpunkt in test_entries.py. Lege zwei Einträge in einem bestimmten Monat an, rufe die Summary für diesen Monat ab und prüfe die Summen. Den einen Test manuell zu schreiben, hilft dir, die Test-Client- und Fixture-Struktur zu verstehen.

Die Datei test_entries.py zeigt die vom Agent geschriebenen Kategorietests neben der manuell geschriebenen Funktion test_monthly_summary. 

Schritt 5: Validierungsschleife fahren

Low oder Medium reichen hier. Tests ausführen und Linting fixen ist reaktiv: Der Agent liest Fehlermeldungen und behebt gezielt – ohne Architekturentscheidungen. Überlass ihm das Testen:

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.

Sieh dir im Agent-Panel den gestreamten pytest-Output an. 

Wenn etwas scheitert, liest der Agent den Traceback, identifiziert die verursachende Datei und wendet den Fix an – alles in derselben Session. Du musst den Fehler nicht in eine neue Nachricht kopieren; die gesamte Debug-/Fix-Schleife bleibt in einem Thread.

Der Screenshot zeigt den Agent-Report nach der Validierungsschleife. Hier traf ruff auf ein Interpreter-Problem durch ein pyenv/.python-version-Mismatch der lokalen Maschine – kein Codefehler. 

Wichtig ist, was hier passiert ist: Der Agent stieß auf ein Umgebungsproblem außerhalb unseres Codes, leitete die Ursache her und fand eigenständig einen Workaround. Genau bei dieser kontextuellen Fehlersuche über Toolgrenzen hinweg setzt GPT-5.6 Sol sichtbar an.

Ebenfalls sinnvoll: „Do not modify test assertions to make them pass“ in jeden Validierungs-Prompt. Ohne diese Leitplanke nehmen Agenten manchmal den Weg des geringsten Widerstands und schwächen Tests, statt das Verhalten zu korrigieren.

Schritt 6: Code-Review-Pass

Setze vor diesem Schritt zurück auf High oder auf Extra High/Max, wenn Sol gründlich auch auf Randfälle kauen soll. Oberflächliches Reasoning erzeugt hier falsche Sicherheit – das Modell soll potenzielle Probleme wirklich durchdenken, nicht nur Muster erkennen.

Bevor du das Projekt abschließt, nutze den Agenten für ein 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.

Der Agent fand, dass DELETE /api/v1/entries/{entry_id} korrekt die Codes 204 und 404 zurückgibt (mit Datei:Zeile-Verweisen), dass GET-Routen auf korrekten 200-Defaults basieren und dass keine Nutzereingaben die Datenbank am ORM vorbei erreichen.

Nach der Sichtung schickst du die Folgeanweisung, um Fixes anzuwenden:

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.

Schritt 7: README und CI-Workflow

Zwei letzte Handgriffe. Für beide reicht Low. Die README-Struktur ist erwartbar, die CI-YAML ist im Grunde Boilerplate – hier bringt mehr Reasoning keinen Mehrwert und kostet nur Credits.

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

Und danach:

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

Nach allen sieben Schritten sieht die Projektstruktur so aus:

Abschließende Gedanken

Wir haben hier eine kleine API gebaut – der Workflow skaliert aber auf alles. 

Leg die AGENTS.md an, bevor der Agent die erste Datei anfasst. Fordere bei allem Nichttrivialen den Plan vor der Ausführung an. Staffel deine Prompts, damit du natürliche Checkpoints hast, statt einen riesigen Diff auf einmal. Nutze @filename für gezielte Fragen zu einer konkreten Datei. Und fahr einen Review-Pass, bevor du etwas als „fertig“ betrachtest – du findest fast immer noch etwas.

GPT-5.6 Sol in Cursor bleibt in langen Sessions spürbar besser auf Kurs, fängt Datei-übergreifende Inkonsistenzen ab und weiß öfter, wann es pausieren und nachfragen sollte, statt destruktiv voranzupreschen. Aber das Modell ist nur ein Teil. Der Kontext zu Beginn, die Validierungsschleifen unterwegs und der Review-Pass am Ende – dort entsteht der große Qualitätsgewinn.

Daumenregel für Reasoning-Level: Nutze High für Architekturentscheidungen, Multi-File-Koordination und nicht offensichtliches Debugging; nutze Medium oder Low für Doku, Boilerplate und Ein-Datei-Edits, bei denen die KI nur tippen soll. Ziehe Extra High oder Max für Code-Reviews in Betracht und überall dort, wo Fehler teurer sind als ein gründlicher Agent-Lauf.