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

¿Qué es Cursor?

Cursor comenzó como un VS Code con funciones de IA integradas, y a simple vista sigue pareciéndose. El editor, el árbol de archivos, el terminal, las extensiones, todo te resultará familiar. 

Lo que se ha reconstruido por debajo es el supuesto de que la IA no solo responde a preguntas al margen, sino que trabaja contigo, por eso tienes el modo agente, indexación del código, un selector de modelo para alternar entre modelos punteros durante la sesión, e inserciones en línea que predicen tu próximo paso con todo el contexto de lo que has estado haciendo.

Si quieres profundizar en las novedades de Cursor, te recomiendo leer nuestros tutoriales sobre Cursor Automations y Cursor SDK.

¿Qué es GPT-5.6?

GPT-5.6 es la generación más reciente de OpenAI, y no es un único modelo sino tres: Sol, Terra y Luna. Estos nombres corresponden a tres niveles de capacidad, sustituyendo a la antigua etiqueta "Instant".

Resumen de la familia:

• Sol es el buque insignia y el más potente de los tres. Es el único nivel que desbloquea el esfuerzo de razonamiento max y el modo ultra, y es donde las mejoras en programación, biología y ciberseguridad son mayores.

• Terra es el predeterminado para el día a día. OpenAI lo posiciona como competitivo con GPT-5.5 a aproximadamente la mitad de precio.

• Luna es el nivel rápido y económico para trabajos de gran volumen o sensibles a la latencia, y rinde por encima de lo que sugiere su precio.

Para un recorrido de programación, Sol es el nivel que importa, así que eso es lo que usamos aquí. Hay dos ajustes nuevos en Sol, y conviene saber cuál vas a tocar realmente. max es un nivel de esfuerzo de razonamiento por encima de xhigh que permite a un único agente dedicar más tiempo a un problema difícil, y es el tope de la escala que configuras en Cursor. ultra, que reparte el trabajo entre subagentes en paralelo, publica las mejores cifras de OpenAI en benchmarks (91,9% en Terminal-Bench 2.1) pero solo funciona en Codex y la API, así que no lo verás en el selector de Cursor.

Para la tabla completa de benchmarks y los precios de los tres niveles, consulta nuestra guía de GPT-5.6 Sol, Terra y Luna.

Cómo acceder y configurar GPT-5.6 Sol en Cursor

GPT-5.6 Sol está disponible en el selector de modelos de Cursor, y hay un detalle importante: como otros modelos punteros recientes de Cursor, Sol se ejecuta solo en el Max Mode de Cursor. Esto significa que usa toda la ventana de contexto y todas las herramientas, y se factura por uso en lugar de por solicitud, así que vigila el gasto de tokens en ejecuciones largas.

Para seleccionar el modelo:

1. Abre el panel del agente con Cmd+L (Mac) o Ctrl+L (Windows/Linux).
2. Haz clic en el botón Model en la parte inferior del área de entrada (muestra el nombre del modelo actual junto a un pequeño icono).
3. Desactiva Auto si está activado.
4. Busca GPT-5.6 Sol en la lista y haz clic en Edit junto a él.
5. Se abrirá un panel a la derecha, donde puedes ajustar de forma independiente la ventana de contexto, el nivel de razonamiento y el modo rápido.

Elegir el esfuerzo de razonamiento adecuado

Al seleccionar Sol eliges el modelo; el esfuerzo de razonamiento decide cuánto piensa sobre una tarea concreta. Puedes elegir entre:

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

None y Low son los más rápidos y baratos, suficientes para autocompletar o un refactor mecánico donde ya sabes lo que quieres. 

High y Extra High tardan más porque realmente piensan el problema primero, y esa diferencia se nota cuando le pides al agente que planifique algo que cruza varios archivos o depure un fallo cuyo origen no es obvio. 

Max está por encima de Extra High y da a un solo agente el máximo tiempo para un problema difícil. El modo multiagente ultra de Sol solo existe en Codex y la API, así que no lo verás en el selector de Cursor.

Un aviso si vienes de GPT-5.5: los niveles no son equivalentes. La propia guía de OpenAI es empezar un nivel por debajo de lo que usas en una tarea conocida y solo subirlo si el resultado lo necesita. He seguido eso abajo, así que algunos pasos van con menos esfuerzo que en el tutorial equivalente de 5.5.

A lo largo de los pasos prácticos, te sugeriré qué nivel de razonamiento tiene más sentido en cada tarea, pero siéntete libre de probar distintos ajustes y ver cómo cambia la salida.

Elegir tamaño de ventana de contexto y modo de velocidad

También puedes elegir entre una ventana de contexto de 272K o 1M, y activar el modo Fast para generar tokens a ~1,5× de velocidad por un coste aproximado de 2,5× créditos. En interacciones ida y vuelta donde esperas respuestas, Fast suele compensar. Para tareas largas en segundo plano, puedes dejarlo desactivado.

Configuración de Cursor

Vamos a preparar el proyecto en Cursor.

Requisitos previos y configuración inicial

Necesitas un plan de pago de Cursor (Pro o superior) para GPT-5.6 Sol y, como Sol se ejecuta en Max Mode, debes tener la facturación por uso activada en tu cuenta. Python 3.11+ es la única otra dependencia local para este proyecto. Si aún no tienes Cursor instalado, descárgalo en cursor.com, inicia sesión y, desde un terminal:

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

El panel del agente está a la derecha, y el explorador de archivos a la izquierda aún no muestra nada, que es exactamente como quieres empezar antes de dejar que el agente construya la estructura.

Navegar por las superficies de IA de Cursor

Antes de ponernos con la construcción, conviene conocer los tres modos principales de interacción y cuándo usar cada uno, porque elegir el equivocado genera una fricción fácil de evitar.

Autocompletado en línea es la capa de autocompletado en segundo plano. Mientras escribes, aparecen sugerencias en gris según lo que estás tecleando y el contexto del archivo, y las aceptas con Tab. No lo invocas: aparece solo. Es el modo indicado cuando escribes a mano y quieres que el modelo reduzca pulsaciones sin cortarte el flujo.

Ask mode es donde el modelo puede leer tus archivos y responder preguntas sin hacer cambios. Piénsalo como pedir a un compañero que mire el código y te diga qué ve. Es especialmente útil en un código ajeno, cuando quieres entender por qué algo se escribió de cierta forma o estás valorando un enfoque antes de comprometerte con él.

Agent mode es lo que impulsa todo este tutorial. En una sesión de agente, el modelo edita archivos, ejecuta comandos en terminal, instala paquetes, lanza tu suite de tests, lee la salida y vuelve a iterar sobre fallos, todo en un mismo hilo continuo. Es el modo para delegar una tarea, no solo preguntar, y la calidad escala directamente con el contexto que le des al principio. Puedes ver el selector de Agent mode abajo a la izquierda del panel en la captura anterior.

Definir pautas específicas del proyecto con AGENTS.md

Este archivo lo escribes tú, así que aún sin modelo. Cambia primero a High, porque el agente lo leerá en el siguiente prompt. La mayoría de sesiones con agentes se tuercen no porque el modelo falle, sino porque no sabe algo específico del proyecto y lo supone: tu framework, tus convenciones de nombres, qué archivos son intocables, cómo verificar cambios.

Para eso sirve AGENTS.md: un README para el agente, donde escribes lo que para ti es obvio pero para el modelo es invisible. AGENTS.md nació como una iniciativa de OpenAI en 2025 y ahora es el estándar entre herramientas para archivos de instrucciones de agentes (parte de la Agentic AI Foundation de la Linux Foundation, junto al MCP de Anthropic), así que merece la pena aprenderlo una vez y usarlo en todas partes.

Crea un archivo llamado AGENTS.md en la raíz con lo siguiente para fijar tu stack de herramientas, convenciones y límites:

# 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 sección de límites es la que más se omite y también la más importante. Sin ella, a veces los agentes deciden "ayudar" reorganizando o limpiando cosas que no pediste tocar. Decirle al modelo qué está fuera de su alcance es tan útil como decirle qué debe hacer.

AGENTS.md es el estándar entre herramientas, pero si prefieres el equivalente nativo de Cursor que hace lo mismo con archivos .mdc con alcance, nuestro tutorial de Cursor Rules te guía para crear un set para un proyecto web en Python.

Crear una API de control de gastos con GPT-5.5

El proyecto es una API REST para registrar gastos personales. Puedes crear asientos, listarlos con filtrado opcional por categoría, borrarlos y obtener un resumen mensual de gasto. 

Es lo bastante simple para seguirlo sin perderse en la lógica de dominio, pero la implementación incluye capa de base de datos, validación de entrada, modelos de respuesta tipados y varios manejadores de rutas trabajando juntos, suficiente para ver lo que hace el agente en una sesión real multiarchivo.

Paso 1: crear el andamiaje del proyecto

Abre el panel del agente y fija el esfuerzo de razonamiento en High antes de enviar nada. El plan que produce el agente antes de escribir una sola línea solo es útil si hay razonamiento detrás; una respuesta superficial aquí se traduce en decisiones estructurales que luego tendrás que deshacer. Envía este primer 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.

Esa última línea merece estar en todos tus prompts no triviales. Pedir el plan antes de ejecutar te cuesta quizá 15 segundos de lectura, pero te permite cazar decisiones estructurales antes de que se propaguen por una docena de archivos. 

GPT-5.6 Sol con razonamiento High produce planes lo bastante específicos como para ser útiles, no resúmenes vagos, y revisarlo ahora es mucho más rápido que reordenar después.

El agente propone la estructura del proyecto y espera tu aprobación antes de escribir un solo archivo.

Cuando respondas algo como «Tiene buena pinta, adelante», el agente empezará a construir. Verás cómo se rellena en tiempo real el árbol de archivos a la izquierda mientras crea archivos, y el terminal abajo mostrando uv instalando paquetes.

El agente creó un pyproject.toml como parte del esqueleto, con el contenido mostrado como nueva adición.

Cuando termine, dedica un minuto a abrir app/models.py y app/database.py antes de seguir. Confirma que el modelo BudgetEntry tiene al menos los campos id, amount, description, category y date, y que database.py configura el motor SQLite asíncrono sin nada raro. 

Si algo no te cuadra, dilo en el siguiente mensaje antes de continuar. Corregir aquí es barato; después de veinte archivos modificados, no lo es.

Paso 2: implementar los endpoints principales

Mantén el esfuerzo en High, o prueba primero con Medium, ya que Sol en Medium maneja trabajo coordinado multiarchivo que en GPT-5.5 habría requerido High. Envía este prompt de implementación:

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.

El agente toca models.py, database.py, routers/entries.py y main.py en un único pase coordinado. A medida que termina cada archivo, Cursor destaca el nuevo contenido para que lo revises antes de aceptarlo. Verás los controles Undo/Keep al pie de cada archivo cambiado.

La captura muestra el router entries.py tras la implementación del agente, junto con la confirmación de que arrancó el servidor y que el endpoint /docs cargó correctamente. 

Cuando aceptes la implementación y el servidor esté en marcha, abre http://localhost:8000/docs en tu navegador para confirmar que todo está bien cableado.

La documentación autogenerada de FastAPI en /docs, mostrando los tres endpoints registrados correctamente. 

Paso 3: añadir validación de categoría

En este tercer paso, puedes bajar el razonamiento del modelo a Low o Medium. Añadir un enum y dos tests es lo bastante acotado y predecible como para no necesitar ciclos extra de deliberación. 

Ahora mismo, la API acepta cualquier cadena como categoría, lo que generará datos inconsistentes en poco tiempo. Vamos a arreglarlo:

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.

El agente añadirá un enum de categoría en models.py y actualizará el modelo de Pydantic para usarlo. Como Pydantic valida automáticamente contra el enum, las categorías inválidas se rechazan antes de que se ejecute el manejador de ruta.

Debería escribir dos tests a la vez: uno que confirme que una categoría válida se guarda bien y otro que confirme que una inválida devuelve 422.

Usar la referencia @

Tras aceptar esos cambios, prueba la función de contexto @ de Cursor para hacer una verificación rápida:

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

Al escribir @ en el panel del agente se abre un selector de archivos y, al elegir app/models.py, su contenido se incorpora directamente al prompt sin que el agente tenga que buscarlo ni suponer la ruta.

Paso 4: construir el endpoint de resumen mensual

Vuelve a High aquí. La consulta de agregación exige que el agente razone conjuntamente sobre filtrado, agrupación y diseño del modelo de respuesta; fallar en cualquiera obliga a tocar los tres archivos otra vez. Con el CRUD básico listo, añade el endpoint de resumen:

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.

Esta es una tarea de base de datos más interesante porque requiere una consulta filtrada con agregación, no un simple select-all. Observa cómo estructura la consulta en database.py; debería usar la interfaz de SQLModel en lugar de SQL en crudo, y el resultado debe encajar con el modelo de respuesta definido en models.py.

Después de aceptar los cambios, escribe tú mismo un test para este endpoint en test_entries.py. Crea dos entradas en un mes concreto, llama al endpoint de resumen para ese mes y comprueba que los totales cuadran. Escribir este a mano te ayuda a familiarizarte con el cliente de tests y los fixtures.

El archivo test_entries.py muestra los tests de validación de categoría escritos por el agente junto a la función test_monthly_summary escrita manualmente. 

Paso 5: ejecutar el bucle de validación

Low o Medium funcionan bien aquí; ejecutar tests y arreglar lint es trabajo reactivo: el agente lee errores y aplica correcciones puntuales más que tomar decisiones de arquitectura. Devuélvele el testing al 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.

Mira el panel del agente mientras transmite la salida de pytest. 

Si algo falla, el agente lee el traceback, identifica qué archivo introdujo el problema y aplica la corrección, todo en la misma sesión. No tienes que copiar y pegar el error en un mensaje nuevo; el bucle de depuración y arreglo sucede en un único hilo continuo.

La captura muestra el informe del agente tras el bucle completo de validación. En este caso, el chequeo de ruff encontró un problema de resolución del intérprete causado por un desajuste de pyenv/.python-version en la máquina local, no un fallo del código. 

Fíjate en lo ocurrido: el agente se topó con un problema de entorno ajeno al código, razonó su causa y encontró una solución sin que se lo pidiéramos. Ese tipo de resolución contextual de fallos entre herramientas es justo donde GPT-5.6 Sol saca ventaja sobre modelos anteriores.

También conviene incluir "no modifiques las aserciones de los tests para que pasen" en todos tus prompts de validación. Sin esa instrucción, a veces los agentes toman el camino fácil y debilitan lo que comprueba un test en lugar de arreglar el comportamiento real.

Paso 6: pasada de code review

Vuelve a High antes de enviar esto, o sube a Extra High/Max si quieres que Sol exprima los casos límite que una sola pasada en High podría rozar. En este paso, un razonamiento superficial da falsa seguridad; quieres que el modelo recorra todos los posibles problemas, no solo haga pattern matching con los más obvios. 

Antes de dar el proyecto por cerrado, usa el agente para una revisión:

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.

El agente encontró que DELETE /api/v1/entries/{entry_id} devuelve correctamente los códigos 204 y 404 (con referencias archivo:línea), que las rutas GET se apoyan en los 200 por defecto adecuados y confirmó que ninguna entrada de usuario llega a la base de datos fuera del ORM.

Cuando revises la lista, envía el seguimiento para aplicar las correcciones:

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.

Paso 7: README y flujo de CI

Dos toques finales para cerrar el proyecto como es debido. Puedes bajar el razonamiento del modelo a Low en ambos. La estructura del README es predecible y el YAML de CI es casi boilerplate, así que no hay gran cosa que razonar; pagar por razonamiento alto aquí es malgastar créditos.

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

Y después:

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

Tras los siete pasos, la estructura del proyecto queda así:

Reflexiones finales

Lo que hemos construido aquí es una API pequeña, pero el flujo de trabajo escala a lo que quieras. 

Ten el AGENTS.md listo antes de que el agente toque un solo archivo. Pide el plan antes de ejecutar en cualquier cosa no trivial. Encadena tus prompts para tener puntos de control naturales y no una macro-diff que revisar de golpe. Usa @filename cuando quieras preguntar algo concreto sobre un archivo. Y haz una pasada de revisión antes de dar por cerrada cualquier tarea, porque casi siempre aparecerá algo.

GPT-5.6 Sol en Cursor se nota mejor que combinaciones anteriores a la hora de mantenerse en la tarea en sesiones largas, detectar inconsistencias entre archivos y saber cuándo parar y consultar antes de seguir con algo destructivo. Pero el modelo es solo una parte. El contexto que le das al principio, los bucles de validación que ejecutas y la revisión final son lo que realmente eleva la calidad del resultado.

Una buena regla general sobre los niveles de razonamiento: usa High para decisiones de arquitectura, coordinación multiarchivo y depuración de algo no obvio; usa Medium o Low para documentación, boilerplate y ediciones de un solo archivo donde básicamente le pides al modelo que teclee. Considera Extra High o Max para code reviews y donde los errores cuestan más que una pasada exhaustiva del agente.