Tutoriel Cursor en mode agent : créer une API REST avec GPT-5.6 Sol

Qu’est-ce que Cursor ?

Cursor a démarré comme un VS Code avec des fonctionnalités IA greffées, et en surface, il y ressemble encore. L’éditeur, l’arborescence de fichiers, le terminal, les extensions : tout est familier.

Ce qui a été repensé en profondeur, c’est l’idée que l’IA ne se contente pas de répondre sur le côté : elle travaille réellement à vos côtés. D’où le mode agent, l’indexation du code, un sélecteur de modèles pour passer d’un modèle à l’autre en cours de session, et des complétions en ligne qui anticipent votre prochaine action en tenant compte de tout le contexte.

Si vous souhaitez explorer davantage les nouveautés de Cursor, consultez nos tutoriels sur Cursor Automations et Cursor SDK.

Qu’est-ce que GPT-5.6 ?

GPT-5.6 est la toute dernière génération de modèles d’OpenAI. Ce n’est pas un seul modèle, mais trois : Sol, Terra et Luna. Ces noms désignent trois niveaux de capacités distincts, qui remplacent l’ancien label « Instant ».

En résumé :

• Sol est le vaisseau amiral, le plus performant des trois. C’est le seul palier qui déverrouille le niveau d’effort de raisonnement max et le mode ultra, et c’est là que les gains en code, biologie et cybersécurité sont les plus nets.

• Terra est le choix du quotidien. OpenAI le positionne au niveau de GPT-5.5 pour un coût environ divisé par deux.

• Luna est le palier rapide et économique pour les volumes élevés ou les cas sensibles à la latence, et ses performances dépassent ce que son prix laisse attendre.

Pour un pas-à-pas orienté code, Sol est le palier qui compte, et c’est celui que nous utilisons ici. Deux réglages sont nouveaux sur Sol, et il est utile de savoir lequel vous utiliserez vraiment. max est un niveau d’effort de raisonnement au-dessus de xhigh qui permet à un agent unique de passer plus de temps sur un problème difficile, et c’est le sommet de l’échelle disponible dans Cursor. ultra, qui parallélise le travail entre sous-agents, affiche les meilleurs scores de benchmarks d’OpenAI (91,9 % sur Terminal-Bench 2.1) mais ne fonctionne que dans Codex et l’API — vous ne le verrez pas dans le sélecteur Cursor.

Pour le tableau complet des benchmarks et la grille tarifaire des trois paliers, consultez notre guide GPT-5.6 Sol, Terra et Luna.

Accéder à GPT-5.6 Sol dans Cursor et le configurer

GPT-5.6 Sol est disponible dans le sélecteur de modèles de Cursor. Un point clé dès le départ : comme les autres modèles de pointe récents dans Cursor, Sol ne fonctionne qu’en Max Mode. Il utilise donc la fenêtre de contexte complète et tous les outils, avec une facturation à l’usage plutôt que par requête. Sur les longues sessions, gardez un œil sur la consommation de jetons.

Pour sélectionner le modèle :

1. Ouvrez le panneau Agent avec Cmd+L (Mac) ou Ctrl+L (Windows/Linux).
2. Cliquez sur le bouton Model en bas de la zone de saisie (il affiche le nom du modèle courant avec une petite icône).
3. Désactivez Auto si l’option est activée.
4. Trouvez GPT-5.6 Sol dans la liste et cliquez sur Edit à côté.
5. Un panneau s’ouvre à droite, où vous pouvez régler indépendamment la taille de la fenêtre de contexte, le niveau de raisonnement et le mode rapide.

Choisir le bon effort de raisonnement

Sélectionner Sol choisit le modèle ; l’effort de raisonnement décide à quel point il réfléchit à une tâche donnée. Vous pouvez choisir entre :

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

None et Low sont les plus rapides et les moins coûteux, suffisants pour de l’autocomplétion ou un refactoring mécanique quand vous savez déjà où vous allez.

High et Extra High prennent plus de temps car le modèle réfléchit vraiment au problème en amont. Vous le verrez surtout lorsque vous lui demandez de planifier un changement multi-fichiers ou de déboguer un échec dont la cause n’est pas évidente.

Max se situe au-dessus de Extra High et donne à un seul agent le maximum de temps sur un problème ardu. Le mode multi-agents ultra de Sol n’existe que dans Codex et l’API : il n’apparaît pas dans le sélecteur de Cursor.

Un avertissement si vous venez de GPT-5.5 : les niveaux ne se superposent pas. OpenAI recommande de commencer un cran plus bas que d’habitude sur une tâche familière et de n’augmenter que si le résultat l’exige. C’est l’approche suivie ci-dessous, donc certaines étapes tournent à un effort plus faible que l’équivalent sous 5.5.

Tout au long des étapes pratiques ci-dessous, je suggérerai le niveau de raisonnement le plus adapté à chaque tâche. N’hésitez pas à expérimenter pour comparer les sorties.

Choisir la taille de fenêtre de contexte et le mode vitesse

Vous pouvez également choisir entre une fenêtre de contexte 272K ou 1M, et activer le mode Fast pour générer à environ 1,5× la vitesse, pour un coût en crédits d’environ 2,5×. Pour un aller-retour interactif où vous attendez la réponse, Fast vaut souvent le coup. Pour une tâche de fond plus longue, inutile de l’activer.

Configurer Cursor

Configurons le projet dans Cursor.

Prérequis et configuration initiale

Un abonnement Cursor payant (Pro ou supérieur) est requis pour GPT-5.6 Sol, et comme Sol tourne en Max Mode, la facturation à l’usage doit être activée sur votre compte. Python 3.11+ est la seule autre dépendance locale nécessaire pour ce projet. Si Cursor n’est pas encore installé, téléchargez-le sur cursor.com, connectez-vous, puis depuis un terminal :

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

Le panneau Agent se trouve à droite, et l’explorateur de fichiers à gauche n’affiche encore aucun fichier : c’est exactement là où vous voulez être avant de laisser l’agent construire la structure.

Parcourir les surfaces IA de Cursor

Avant d’attaquer la construction, il vaut la peine de connaître les trois modes d’interaction principaux et quand les utiliser. Choisir le mauvais crée une friction facile à éviter.

Complétion en ligne est la couche d’autocomplétion en arrière-plan. En tapant, des suggestions grisées apparaissent selon ce que vous écrivez et le contexte du fichier ; validez avec Tab. Vous ne l’invoquez pas : elle apparaît. C’est le bon mode quand vous codez à la main et voulez réduire les frappes sans casser votre flux.

Ask mode permet au modèle de lire vos fichiers et répondre à vos questions sans rien modifier. Pensez-y comme à un collègue qui jette un œil et vous donne son avis. Particulièrement utile dans un code inconnu, pour comprendre un choix, ou pour tester une approche avant de s’engager.

Agent mode alimente tout ce tutoriel. En session agent, le modèle édite des fichiers, lance des commandes terminal, installe des packages, exécute votre suite de tests, lit les sorties et reboucle sur les échecs, le tout dans un même fil. Ici, vous confiez une tâche, vous ne posez pas juste une question ; la qualité dépend directement du contexte que vous fournissez. Le sélecteur Agent mode est en bas à gauche du panneau sur la capture ci-dessus.

Poser un cadre spécifique au projet avec AGENTS.md

Vous écrivez ce fichier vous-même, donc pas de modèle pour l’instant. Passez d’abord en High, car le prochain prompt est celui où l’agent le lira. La plupart des sessions d’agent dérapent non pas parce que le modèle s’est trompé, mais parce qu’il a dû deviner un détail propre à votre projet : votre framework, vos conventions de nommage, les fichiers intouchables, comment valider les changements.

C’est le rôle d’AGENTS.md : un README pour l’agent, où vous notez ce qui est évident pour vous mais invisible pour le modèle. AGENTS.md a débuté comme une initiative d’OpenAI en 2025 et est désormais le standard inter-outils pour les fichiers d’instructions d’agents (au sein de l’Agentic AI Foundation de la Linux Foundation, aux côtés du MCP d’Anthropic), donc apprenez-le une fois et réutilisez-le partout.

Créez un fichier AGENTS.md à la racine du projet avec ceci pour fixer la stack, les conventions et le périmètre :

# 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 section « boundaries » est celle qu’on zappe le plus souvent, alors que c’est la plus importante. Sans elle, les agents décident parfois de « rendre service » en réorganisant ou nettoyant des éléments non demandés. Dire au modèle ce qui est hors périmètre est aussi utile que de lui dire quoi faire.

AGENTS.md est le standard inter-outils, mais si vous préférez l’équivalent natif Cursor via des fichiers .mdc scopés, notre tutoriel Cursor Rules montre comment en bâtir un ensemble pour un projet web Python.

Construire une API de suivi de budget avec GPT-5.5

Le projet est une API REST pour suivre des entrées de budget personnel. Vous pouvez créer des entrées, les lister avec un filtre de catégorie optionnel, les supprimer, et récupérer un récapitulatif mensuel des dépenses.

C’est assez simple pour suivre sans se perdre dans le fonctionnel, mais l’implémentation implique une couche base de données, la validation d’entrées, des modèles de réponse typés, et plusieurs route handlers qui coopèrent : suffisant pour voir l’agent à l’œuvre sur une vraie session multi-fichiers.

Étape 1 : générer l’ossature du projet

Ouvrez le panneau agent et réglez l’effort de raisonnement sur High avant d’envoyer quoi que ce soit. Le plan produit avant d’écrire la moindre ligne ne vaut que par la qualité du raisonnement en amont : une réponse superficielle ici, c’est des choix structurels que vous démaillerez plus tard. Envoyez ce prompt en premier :

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.

Cette dernière phrase vaut la peine d’être dans tous vos prompts non triviaux. Demander le plan avant l’exécution vous coûte 15 secondes de lecture, et vous évite de laisser se propager des choix mal orientés dans une douzaine de fichiers.

GPT-5.6 Sol en High produit des plans suffisamment précis pour être exploitables, pas de vagues résumés. Revoir la structure maintenant est bien plus rapide qu’une réorganisation plus tard.

L’agent propose le layout du projet et attend votre validation avant d’écrire le moindre fichier.

Dès que vous répondez « C’est bon, allez-y », l’agent se met à construire. Sur la gauche, l’arborescence se peuple en temps réel, pendant que le terminal en bas montre uv en train d’installer les packages.

L’agent a créé un pyproject.toml dans l’ossature, avec le contenu du fichier affiché comme nouvel ajout.

Après la génération, prenez une minute pour ouvrir app/models.py et app/database.py avant d’avancer. Vérifiez que le modèle BudgetEntry contient au moins les champs id, amount, description, category et date, et que database.py configure bien le moteur SQLite async sans rien d’inhabituel.

Si quelque chose cloche, dites-le au prochain message plutôt que de continuer. Corriger à ce stade coûte peu ; après vingt fichiers modifiés, beaucoup plus.

Étape 2 : implémenter les endpoints cœurs

Restez en High, ou testez Medium d’abord : Sol en Medium gère des travaux coordonnés multi-fichiers qui auraient exigé High sous GPT-5.5. Envoyez le prompt d’implémentation :

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’agent touche models.py, database.py, routers/entries.py et main.py en un seul passage coordonné. À mesure qu’il termine chaque fichier, Cursor affiche le contenu ajouté en surbrillance pour relecture, avec les contrôles Undo/Keep en bas de chaque fichier changé.

La capture montre le routeur entries.py après implémentation par l’agent, avec confirmation du démarrage du serveur et du chargement correct de /docs.

Une fois l’implémentation acceptée et le serveur lancé, ouvrez http://localhost:8000/docs dans votre navigateur pour confirmer que tout est bien raccordé.

La documentation auto-générée de FastAPI sur /docs, avec les trois endpoints correctement enregistrés.

Étape 3 : ajouter une validation des catégories

Pour cette troisième étape, vous pouvez abaisser le raisonnement à Low ou Medium. Ajouter un enum et deux tests est assez borné et prévisible : inutile de payer pour plus de délibération.

Actuellement, l’API accepte n’importe quelle chaîne comme catégorie, ce qui créera vite des données incohérentes. Corrigeons cela :

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’agent ajoutera un enum de catégories dans models.py et mettra à jour le modèle Pydantic pour l’utiliser. Comme Pydantic valide automatiquement contre l’enum, les catégories invalides sont rejetées avant même d’arriver au route handler.

Il écrira deux tests à côté : l’un confirmant qu’une catégorie valide est bien enregistrée, l’autre qu’une catégorie invalide renvoie un 422.

Utiliser la référence @

Après avoir accepté ces changements, testez la fonctionnalité de contexte @ de Cursor pour poser une question de vérification rapide :

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

Taper @ dans le panneau agent ouvre un sélecteur de fichiers ; une fois app/models.py choisi, son contenu est injecté directement dans le prompt sans que l’agent ait à chercher ni à deviner le chemin.

Étape 4 : créer l’endpoint de synthèse mensuelle

Revenez sur High. La requête d’agrégation demande à l’agent de raisonner sur le filtrage, le groupement et la conception du modèle de réponse ensemble ; une erreur sur l’un de ces points implique de retoucher trois fichiers. Avec le CRUD en place, ajoutez l’endpoint de synthèse :

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.

C’est une tâche base de données plus intéressante car elle nécessite une requête filtrée avec agrégation et non un simple select-all. Regardez comment l’agent structure la requête dans database.py : il doit utiliser l’interface de requêtes de SQLModel plutôt que du SQL brut, et le résultat doit s’adapter naturellement au modèle de réponse défini dans models.py.

Après avoir accepté les changements, écrivez vous-même un test pour cet endpoint dans test_entries.py. Créez deux entrées dans un mois donné, appelez la synthèse pour ce mois, et vérifiez les totaux. L’écrire à la main est un bon moyen de vous familiariser avec le client de test et les fixtures.

Le fichier test_entries.py présente les tests de validation des catégories écrits par l’agent, ainsi que la fonction test_monthly_summary écrite manuellement.

Étape 5 : exécuter la boucle de validation

Low ou Medium suffisent ici : exécuter les tests et corriger le lint est réactif ; l’agent lit les erreurs et applique des correctifs ciblés sans décisions architecturales. Confiez-lui les tests :

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.

Suivez la sortie pytest en streaming dans le panneau agent.

En cas d’échec, l’agent lit la traceback, identifie le fichier en cause et applique le correctif dans la même session. Pas besoin de copier-coller l’erreur dans un nouveau message : le débogage et la correction se font dans un fil continu.

La capture montre le compte rendu de l’agent après la validation complète. Ici, ruff check a rencontré un problème de résolution d’interprète causé par un décalage pyenv/.python-version local, et non un souci de code.

Notez bien : l’agent a rencontré un problème d’environnement sans lien avec le code, en a analysé la cause et a trouvé une solution de contournement sans consigne supplémentaire. Ce type de résolution contextuelle face à des défaillances d’outils est précisément là où GPT-5.6 Sol se distingue.

Incluez systématiquement « ne modifiez pas les assertions des tests pour les faire passer » dans vos prompts de validation. Sinon, certains agents suivent la voie de la facilité et affaiblissent les tests au lieu de corriger le comportement.

Étape 6 : passe de revue de code

Repassez en High pour ce prompt, ou Extra High/Max si vous voulez que Sol balaie les cas limites qu’un simple High pourrait survoler. À cette étape, un raisonnement superficiel donne un faux sentiment de sécurité : vous voulez que le modèle évalue réellement tous les points d’attention, pas qu’il fasse du pattern matching.

Avant de clore le projet, demandez une revue à l’agent :

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’agent confirme que DELETE /api/v1/entries/{entry_id} renvoie correctement les codes 204 et 404 (avec références fichier:ligne), que les routes GET s’appuient sur des 200 par défaut corrects, et qu’aucune entrée utilisateur n’atteint la base hors ORM.

Après revue, envoyez le suivi pour appliquer les correctifs :

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.

Étape 7 : README et workflow CI

Deux dernières touches pour conclure proprement. Vous pouvez baisser le raisonnement à Low pour les deux : la structure du README est prévisible, et le YAML de CI est du quasi boilerplate. Payer pour un haut niveau ici serait du crédit gaspillé.

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

Puis :

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

Après ces sept étapes, la structure du projet ressemble à ceci :

Conclusion

Ce que nous avons construit ici est une petite API, mais le flux de travail s’adapte à tout.

Mettez en place AGENTS.md avant que l’agent ne touche un seul fichier. Demandez le plan avant l’exécution pour tout ce qui n’est pas trivial. Cadencez vos prompts pour créer des points d’arrêt naturels, plutôt qu’un seul gigantesque diff à relire. Utilisez @filename pour des questions ciblées sur un fichier. Et faites une passe de revue avant de clore une tâche : on découvre presque toujours quelque chose.

GPT-5.6 Sol dans Cursor est nettement meilleur que les combinaisons précédentes pour rester concentré sur de longues sessions, réconcilier des incohérences entre fichiers et savoir s’arrêter pour demander validation plutôt que foncer vers des changements destructeurs. Mais le modèle n’est qu’une partie de l’équation : le contexte initial, les boucles de validation et la passe de revue finale, c’est là que se joue l’amélioration réelle de la qualité.

Règle pratique pour les niveaux de raisonnement : utilisez High pour les décisions d’architecture, la coordination multi-fichiers et le débogage non évident ; Medium ou Low pour la documentation, le boilerplate et les éditions mono-fichier où vous demandez au modèle de faire la frappe. Envisagez Extra High ou Max pour les revues de code ou lorsque l’erreur coûterait plus cher qu’une passe approfondie.