Samouczek trybu agenta w Cursorze: budowa REST API z GPT-5.6 Sol

Czym jest Cursor?

Cursor startował jako VS Code z doszytymi funkcjami AI i z wierzchu wciąż tak wygląda. Edytor, drzewo plików, terminal, rozszerzenia — wszystko znajome. 

To, co przebudowano pod spodem, to założenie, że AI nie tylko odpowiada na boku, ale faktycznie pracuje razem z tobą. Dlatego masz tryb agenta, indeksowanie kodu, selektor modeli pozwalający przełączać się między modelami klasy frontier w środku sesji oraz podpowiedzi inline przewidujące twój następny ruch na podstawie pełnego kontekstu dotychczasowej pracy.

Jeśli chcesz zgłębić najnowsze funkcje Cursora, polecam nasze tutoriale o Cursor Automations i Cursor SDK.

Czym jest GPT-5.6?

GPT-5.6 to najnowsza generacja modeli OpenAI i to nie jeden model, lecz trzy: Sol, Terra i Luna. Te nazwy oznaczają trzy odrębne poziomy możliwości, zastępując dawną etykietę „Instant”.

Krótko o rodzinie:

• Sol to flagowiec i najsilniejszy z trzech. Tylko ten poziom odblokowuje nowy wysiłek rozumowania max oraz tryb ultra, i to tutaj zyski w kodowaniu, biologii czy cyberbezpieczeństwie są największe.

• Terra to codzienny domyślny wybór. OpenAI pozycjonuje ją jako konkurencyjną względem GPT-5.5 przy mniej więcej połowie ceny.

• Luna to szybki, tani poziom do zadań wielkoskalowych lub wrażliwych na opóźnienia — mocniejszy, niż sugeruje cena.

W praktycznym przejściu przez kod liczy się Sol, więc tu z niego korzystamy. Dwa ustawienia w Sol są nowe i warto wiedzieć, które faktycznie użyjesz. max to poziom wysiłku rozumowania powyżej xhigh, pozwalający jednemu agentowi spędzić więcej czasu nad trudnym problemem, i to najwyższy szczebel, jaki ustawisz w Cursorze. ultra, które dzieli pracę między równoległe sub-agenty, osiąga najlepsze wyniki OpenAI w benchmarkach (91,9% na Terminal-Bench 2.1), ale działa tylko w Codexie i API, więc nie znajdziesz go w selektorze Cursora.

Pełną tabelę benchmarków i ceny trzech poziomów znajdziesz w naszym przewodniku po GPT-5.6 Sol, Terra i Luna.

Jak uzyskać dostęp do GPT-5.6 Sol w Cursorze i jak go skonfigurować

GPT-5.6 Sol jest dostępny w selektorze modeli Cursora i jest jedna rzecz, którą warto wiedzieć od razu: jak inne najnowsze modele frontier w Cursorze, Sol działa wyłącznie w Max Mode. To znaczy, że używa pełnego okna kontekstu i wszystkich narzędzi, a rozliczany jest według użycia, a nie per żądanie — więc miej oko na zużycie tokenów przy długich przebiegach.

Aby wybrać model:

1. Otwórz panel agenta skrótem Cmd+L (Mac) lub Ctrl+L (Windows/Linux).
2. Kliknij przycisk Model na dole pola wprowadzania (pokazuje nazwę aktualnego modelu obok małej ikony).
3. Wyłącz Auto, jeśli jest włączone.
4. Znajdź GPT-5.6 Sol na liście i kliknij Edit obok.
5. Po prawej otworzy się panel, w którym niezależnie ustawisz okno kontekstu, poziom rozumowania i przełącznik szybkości.

Dobór odpowiedniego wysiłku rozumowania

Wybranie Sol wybiera model; poziom wysiłku rozumowania decyduje, jak głęboko „pomyśli” nad danym zadaniem. Do wyboru masz:

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

None i Low są najszybsze i najtańsze — wystarczające do autouzupełniania lub mechanicznego refaktoringu, gdy zasadniczo wiesz, czego chcesz. 

High i Extra High trwają dłużej, bo model faktycznie najpierw rozpracowuje problem — i różnicę widać szczególnie, gdy prosisz agenta o zaplanowanie czegoś, co obejmuje wiele plików, albo o debug nieoczywistej usterki. 

Max stoi ponad Extra High i daje pojedynczemu agentowi najwięcej czasu na trudny problem. Tryb multiagenta ultra w Sol istnieje tylko w Codexie i API, więc nie zobaczysz go w selektorze Cursora.

Jedno ostrzeżenie, jeśli przechodzisz z GPT-5.5: poziomy nie przekładają się 1:1. OpenAI radzi zacząć o jeden stopień niżej niż zwykle przy znanym zadaniu i podkręcać tylko, jeśli wynik tego potrzebuje. Poniżej tak właśnie robię, więc kilka kroków jedzie na niższym wysiłku niż odpowiadający im tutorial dla 5.5.

W praktycznych krokach poniżej zasugeruję poziom rozumowania, który ma najwięcej sensu dla danego zadania, ale śmiało eksperymentuj z innymi ustawieniami i zobacz, jak zmienia się wynik.

Wybór rozmiaru okna kontekstu i trybu szybkości

Możesz też wybrać okno kontekstu 272K lub 1M oraz włączyć tryb Fast, by generować tokeny ok. 1,5x szybciej za mniej więcej 2,5x kosztu kredytowego. Do interaktywnej rozmowy, gdy czekasz na odpowiedzi, Fast często się opłaca. Do dłuższych zadań w tle, gdy przekazujesz coś agentowi i robisz inne rzeczy, spokojnie zostaw go wyłączonego.

Konfiguracja Cursora

Skonfigurujmy projekt w Cursorze.

Wymagania i wstępna konfiguracja

Do GPT-5.6 Sol potrzebny jest płatny plan Cursora (Pro lub wyższy), a ponieważ Sol działa w Max Mode, w twoim koncie musi być włączone rozliczanie według użycia. Python 3.11+ to jedyna dodatkowa lokalna zależność potrzebna w tym projekcie. Jeśli Cursor nie jest jeszcze zainstalowany, pobierz go z cursor.com, zaloguj się, a następnie w terminalu:

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

Panel Agenta jest po prawej, a po lewej eksplorator plików nie pokazuje jeszcze żadnych plików — dokładnie tak, jak chcesz zacząć, zanim pozwolisz agentowi zbudować strukturę.

Poruszanie się po warstwach AI w Cursorze

Zanim przejdziemy do budowy, warto wiedzieć, jakie są trzy główne tryby interakcji i kiedy który ma sens — użycie niewłaściwego dodaje tarcia, którego łatwo uniknąć.

Uzupełnianie inline to warstwa autouzupełniania w tle. Jak piszesz, pojawiają się wyszarzone sugestie oparte na tym, co wpisujesz i otaczającym kontekście pliku — zatwierdzasz je Tabem. Nie wywołujesz go, po prostu się pojawia. To właściwy tryb, gdy piszesz kod ręcznie i chcesz, by model skracał liczbę naciśnięć klawiszy bez przerywania flow.

Tryb Ask to miejsce, gdzie model może czytać twoje pliki i odpowiadać na pytania bez wprowadzania zmian. Pomyśl o tym jak o poproszeniu kolegi, by zerknął na kod i powiedział, co widzi. Szczególnie przydatny, gdy jesteś w nieznanej bazie kodu, próbujesz zrozumieć, czemu coś napisano tak, a nie inaczej, albo dopiero rozważasz podejście, zanim się na nie zdecydujesz.

Tryb agenta napędza cały ten samouczek. W sesji agenta model edytuje pliki, uruchamia komendy w terminalu, instaluje paczki, odpala zestaw testów, czyta wyniki i zawraca na porażkach — wszystko w jednym ciągłym wątku. To tryb, w którym przekazujesz zadanie, a nie tylko o nie pytasz, a jakość zwrotki rośnie wprost proporcjonalnie do kontekstu, jaki dasz na starcie. Wybierak trybu agenta widać w lewym dolnym rogu panelu na zrzucie powyżej.

Ustalenie wskazówek projektowych w AGENTS.md

Ten plik piszesz samodzielnie, więc jeszcze bez modelu. Najpierw przełącz na High, bo następne polecenie to moment, gdy agent go czyta. Większość sesji agenta skręca w złą stronę nie dlatego, że model popełnił błąd, ale bo czegoś specyficznego dla projektu nie wiedział i zgadł: twojego frameworka, konwencji nazewniczych, plików poza zasięgiem, sposobu weryfikacji zmian.

Od tego jest AGENTS.md: README dla agenta, gdzie zapisujesz to, co dla ciebie oczywiste, a dla modelu niewidoczne. AGENTS.md zaczęło się jako inicjatywa OpenAI w 2025 r. i jest dziś standardem między narzędziami dla plików instrukcji agentów (część Agentic AI Foundation przy Linux Foundation, obok MCP Anthropic), więc warto nauczyć się raz i używać wszędzie.

Utwórz plik AGENTS.md w katalogu głównym projektu z poniższą treścią, by określić stos narzędzi, konwencje i granice:

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

Sekcja z granicami to ta, którą najczęściej się pomija — i jednocześnie najważniejsza. Bez niej agenci potrafią czasem „pomóc”, reorganizując lub „sprzątając” rzeczy, których nie prosiłeś dotykać. Powiedzenie modelowi, czego nie ruszać, jest tak samo przydatne, jak powiedzenie, co ma zrobić.

AGENTS.md to standard między narzędziami, ale jeśli chcesz kursowy odpowiednik natywny dla Cursora, który robi to samo w zawężonych plikach .mdc, nasz tutorial Cursor Rules przeprowadza przez zbudowanie zestawu dla projektu webowego w Pythonie.

Budowa API śledzenia budżetu z GPT-5.5

Projekt to REST API do śledzenia wpisów budżetowych. Możesz tworzyć wpisy, listować je z opcjonalnym filtrowaniem po kategorii, usuwać i pobierać miesięczne podsumowanie wydatków. 

Jest na tyle prosty, by się nie zgubić w logice domenowej, ale implementacja obejmuje warstwę bazy danych, walidację wejścia, typowane modele odpowiedzi i kilka współpracujących handlerów tras — wystarczająco, by pokazać, co agent faktycznie robi w realnej, wieloplikowej sesji.

Krok 1: Szkielet struktury projektu

Otwórz panel agenta i ustaw wysiłek rozumowania na High przed wysłaniem czegokolwiek. Plan, który agent stworzy przed pisaniem kodu, jest tak użyteczny, jak stojące za nim rozumowanie — płytka odpowiedź na tym etapie oznacza decyzje strukturalne, które będziesz później rozplątywać. Zacznij, wysyłając takie polecenie:

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.

Tę ostatnią linijkę warto mieć w każdym nietrywialnym poleceniu do agenta. Prośba o plan przed wykonaniem kosztuje może 15 sekund czytania, ale pozwala wyłapać decyzje strukturalne, zanim rozleją się na kilkanaście plików. 

GPT-5.6 Sol na High potrafi tworzyć plany na tyle konkretne, że faktycznie użyteczne, a przejrzenie struktury teraz jest znacznie szybsze niż późniejsze porządki.

Agent proponuje układ projektu i czeka na akceptację, zanim zapisze choć jeden plik.

Gdy odpiszesz czymś w stylu „Wygląda dobrze, jedź dalej”, agent zacznie budowę. Po lewej zobaczysz, jak w czasie rzeczywistym zapełnia się drzewo plików, a w terminalu na dole uv instaluje paczki.

Agent utworzył pyproject.toml w ramach szkieletu, a zawartość pliku pokazana jest jako nowy dodatek.

Po zakończeniu szkieletu poświęć minutę, by otworzyć app/models.py i app/database.py zanim ruszysz dalej. Potwierdź, że model BudgetEntry ma co najmniej pola id, amount, description, category i date, a database.py konfiguruje asynchroniczny silnik SQLite bez niczego nietypowego. 

Jeśli coś wygląda podejrzanie, powiedz o tym w następnym komunikacie zamiast brnąć dalej. Poprawki na tym etapie są tanie; po zmianach w dwudziestu plikach — już nie.

Krok 2: Implementacja kluczowych endpointów

Zostaw wysiłek na High albo spróbuj najpierw Medium, bo Sol na Medium ogarnia skoordynowaną pracę na wielu plikach, która w GPT-5.5 wymagała High. Wyślij polecenie implementacji:

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.

Agent dotknie models.py, database.py, routers/entries.py i main.py w jednym, skoordynowanym przebiegu. Gdy kończy każdy plik, Cursor pokazuje nową zawartość podświetloną w edytorze, byś mógł ją przejrzeć przed akceptacją. Zobaczysz kontrolki Undo/Keep na dole każdego zmienionego pliku.

Zrzut ekranu pokazuje router entries.py po implementacji przez agenta oraz potwierdzenie, że serwer został uruchomiony i endpoint /docs ładuje się poprawnie. 

Po zaakceptowaniu zmian i uruchomieniu serwera otwórz w przeglądarce http://localhost:8000/docs, aby potwierdzić, że wszystko jest poprawnie spięte.

Automatyczne dokumenty FastAPI pod /docs, pokazujące trzy endpointy zarejestrowane poprawnie. 

Krok 3: Dodanie walidacji kategorii

W tym kroku możesz obniżyć wysiłek modelu do Low lub Medium. Dodanie enuma i dwóch testów jest na tyle samoobsługowe i przewidywalne, że nie trzeba tu przepalać dodatkowych cykli rozumowania. 

Obecnie API akceptuje dowolny string jako kategorię, co szybko skończy się niespójnością danych. Naprawmy to:

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.

Agent doda enum kategorii do models.py i zaktualizuje model Pydantic, by go używał. Ponieważ Pydantic automatycznie waliduje wobec enumów, nieprawidłowe kategorie są odrzucane, zanim handler trasy w ogóle ruszy.

Powinny też powstać dwa testy obok: jeden potwierdzający, że prawidłowa kategoria zapisuje się poprawnie, drugi — że nieprawidłowa zwraca 422.

Korzystanie z odwołania @

Po zaakceptowaniu zmian wypróbuj funkcję kontekstu Cursora z @, by zadać szybkie pytanie weryfikacyjne:

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

Wpisanie @ w panelu agenta otwiera selektor plików, a po wybraniu app/models.py zawartość pliku jest wciągana bezpośrednio do promptu, bez potrzeby szukania przez agenta czy zgadywania ścieżki.

Krok 4: Endpoint miesięcznego podsumowania

Wróć do High. Zapytanie agregujące wymaga, by agent naraz rozumował o filtrowaniu, grupowaniu i projekcie modelu odpowiedzi, a pomyłka w którejkolwiek z tych rzeczy oznacza dotykanie trzech plików ponownie. Mając działające CRUD, dodaj endpoint podsumowania:

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.

To ciekawsze zadanie bazodanowe, bo wymaga filtrowanego zapytania z agregacją, a nie zwykłego select-all. Zwróć uwagę, jak agent buduje zapytanie w database.py; powinien używać interfejsu zapytań SQLModel, a nie surowego SQL, a wynik ma się czysto mapować na model odpowiedzi zdefiniowany w models.py.

Po zaakceptowaniu zmian napisz sam jeden test dla tego endpointu w test_entries.py. Utwórz dwa wpisy w konkretnym miesiącu, wywołaj endpoint podsumowania dla tego miesiąca i sprawdź sumy. Zrobienie tego ręcznie zamiast proszenia agenta to dobry sposób, by oswoić się z klientem testowym i fixture’ami.

Plik test_entries.py pokazuje testy walidacji kategorii napisane przez agenta obok ręcznie stworzonej funkcji test_monthly_summary. 

Krok 5: Pętla walidacji

Low lub Medium w zupełności wystarczy — uruchamianie testów i poprawianie lintów to praca reaktywna, agent czyta błędy i stosuje celowane poprawki, a nie podejmuje decyzji architektonicznych. Przekaż testowanie z powrotem agentowi:

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.

Obserwuj panel agenta, gdy strumieniuje wynik pytesta. 

Jeśli coś pada, agent czyta traceback, identyfikuje, który plik wprowadził problem, i stosuje poprawkę — wszystko w tej samej sesji. Nie musisz kopiować błędu do nowej wiadomości; cały cykl debugowania i poprawek dzieje się w jednym ciągłym wątku.

Zrzut pokazuje raport agenta po pełnej pętli walidacji. W tym przypadku ruff trafił na problem z rozpoznaniem interpretera spowodowany niezgodnością pyenv/.python-version na lokalnej maszynie, a nie problemem w kodzie. 

Warto zauważyć, co się stało: agent napotkał problem środowiskowy niezwiązany z naszym kodem, wyjaśnił jego przyczynę i znalazł obejście bez podpowiedzi. Takie kontekstowe rozwiązywanie problemów ponad awariami narzędzi to dokładnie obszar, w którym GPT-5.6 Sol wyprzedza wcześniejsze modele.

Warto też w każdym poleceniu walidacyjnym dopisać „nie modyfikuj asercji testów, żeby przeszły”. Bez tego czasem wybiorą najprostszy opór materii i osłabią test zamiast naprawić zachowanie.

Krok 6: Przegląd kodu

Ustaw znów High przed wysłaniem, albo Extra High/Max, jeśli chcesz, by Sol przewałkował przypadki brzegowe, które pojedynczy przebieg High mógłby prześlizgnąć. Na tym etapie płytkie rozumowanie daje fałszywe poczucie bezpieczeństwa; chcesz, żeby model rzeczywiście przepracował potencjalne problemy, a nie tylko dopasował wzorce do najbardziej oczywistych.

Zanim uznasz projekt za skończony, użyj agenta do przeglądu:

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.

Agent znalazł, że DELETE /api/v1/entries/{entry_id} poprawnie zwraca kody 204 i 404 (z referencjami plik:linia), że trasy GET polegają na domyślnych 200, i potwierdził, że żaden input użytkownika nie trafia do bazy poza ORM-em.

Gdy przejrzysz listę, wyślij follow-up, by zastosować poprawki:

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.

Krok 7: README i workflow CI

Dwa ostatnie szlify, by porządnie zamknąć projekt. Możesz obniżyć rozumowanie modelu do Low w obu. Struktura README jest przewidywalna, a YAML CI to w zasadzie boilerplate, więc nie ma tu nad czym rozumować — płacenie za wysoki wysiłek to marnowanie kredytów.

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

A potem:

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

Po wszystkich siedmiu krokach struktura projektu wygląda tak:

Na koniec

Zbudowaliśmy tu małe API, ale workflow skalowalny jest do wszystkiego. 

Zadbaj o AGENTS.md zanim agent dotknie choć jednego pliku. Proś o plan przed wykonaniem przy wszystkim, co nietrywialne. Dziel polecenia na etapy, żeby mieć naturalne punkty kontrolne zamiast jednego gigantycznego diffu do przeglądu naraz. Używaj @filename, gdy chcesz zadać celne pytanie o konkretny plik. I zrób przegląd przed uznaniem zadania za skończone — prawie zawsze coś złapiesz.

GPT-5.6 Sol w Cursorze wyraźnie lepiej niż wcześniejsze kombinacje trzyma się zadania przez długie sesje, wyłapuje niespójności między plikami i wie, kiedy się zatrzymać i dopytać zamiast iść na oślep w coś destrukcyjnego. Ale model to tylko część układanki. Kontekst, który dasz na początku, pętle walidacji i przegląd na końcu — tam rodzi się realna poprawa jakości wyników.

Dobra reguła kciuka dla poziomów rozumowania: używaj High do decyzji architektonicznych, koordynacji wielu plików i debugowania nieoczywistości; Medium lub Low do dokumentacji, boilerplate’u i pojedynczych plików, gdzie prosisz model głównie o „pisanie za ciebie”. Rozważ Extra High lub Max przy przeglądach kodu i tam, gdzie błędy są droższe niż gruntowny przebieg agenta.