Учебник по режиму агента в Cursor: создаем REST API с GPT-5.6 Sol

Что такое Cursor?

Cursor начинался как VS Code с «пришитыми» AI-функциями и внешне до сих пор на него похож. Редактор, дерево файлов, терминал, расширения — всё знакомо. 

Под капотом перестроено главное допущение: AI не просто отвечает на вопросы, а действительно работает вместе с вами. Отсюда — режим агента, индексирование кодовой базы, селектор моделей, позволяющий переключаться между передовыми моделями в ходе одной сессии, и встроенные автодополнения, предсказывающие ваш следующий шаг на основе полного контекста вашей работы.

Если вам интересно глубже изучить новые возможности Cursor, рекомендую наши учебники по Cursor Automations и Cursor SDK.

Что такое GPT-5.6?

GPT-5.6 — это новое поколение моделей OpenAI, и это не одна модель, а три: Sol, Terra и Luna. Эти названия обозначают три разных уровня возможностей, заменив прежнюю метку «Instant».

Коротко о семействе:

• Sol — флагман и самая мощная из трёх. Это единственный уровень, который открывает новый уровень усилий на рассуждение max и режим ultra; именно здесь наибольший прирост в кодинге, биологии и кибербезопасности.

• Terra — повседневный дефолт. OpenAI позиционирует её как сопоставимую с GPT-5.5 примерно за половину цены.

• Luna — быстрый и недорогой уровень для задач с большим объёмом или жёсткими требованиями к задержке; она сильнее, чем можно подумать по цене.

Для пошагового руководства по кодингу важна Sol, поэтому мы используем её. Два параметра в Sol — новые, и стоит понимать, какой из них вам действительно пригодится. max — это уровень усилий на рассуждение выше xhigh, позволяющий одному агенту дольше работать над сложной задачей; это верхняя планка, доступная в Cursor. ultra, который распределяет работу между параллельными субагентами, показывает лучшие бенчмарки OpenAI (91,9% на Terminal-Bench 2.1), но доступен только в Codex и API, поэтому в селекторе Cursor вы его не найдёте.

Полную таблицу бенчмарков и цены по трём уровням смотрите в нашем руководстве GPT-5.6 Sol, Terra и Luna.

Как получить доступ к GPT-5.6 Sol в Cursor и настроить её

GPT-5.6 Sol доступна в селекторе моделей Cursor, и важно знать одну вещь заранее: как и другие недавние передовые модели в Cursor, Sol работает только в Max Mode. Это означает использование полного контекстного окна и всех инструментов, а биллинг идёт по использованию, а не за запрос, поэтому следите за расходом токенов при длинных прогонах.

Чтобы выбрать модель:

1. Откройте панель агента сочетанием Cmd+L (Mac) или Ctrl+L (Windows/Linux).
2. Нажмите кнопку Model внизу поля ввода (рядом показано имя текущей модели и небольшая иконка).
3. Если включён режим Auto, выключите его.
4. Найдите GPT-5.6 Sol в списке и нажмите Edit рядом с ней.
5. Справа откроется панель, где вы можете независимо задать размер контекстного окна, уровень рассуждения и быстрый режим.

Подбор подходящего уровня рассуждения

Выбор Sol определяет модель; уровень рассуждения определяет, насколько тщательно она подумает над задачей. Можно выбрать:

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

None и Low — самые быстрые и дешёвые, подходят для автодополнения или механического рефакторинга, когда вы и так знаете, чего хотите. 

High и Extra High занимают больше времени, потому что модель сначала действительно продумывает проблему. Это особенно заметно, когда вы просите агента спланировать что-то, затрагивающее несколько файлов, или отладить сбой с неочевидной причиной. 

Max находится выше Extra High и даёт одному агенту больше всего времени на сложную задачу. Мультиагентный режим Sol ultra существует только в Codex и API, поэтому в селекторе Cursor вы его не увидите.

Предупреждение для тех, кто приходит с GPT-5.5: уровни не сопоставимы напрямую. Рекомендация OpenAI — начать на один уровень ниже привычного для знакомой задачи и повышать только при необходимости. Я следовал этому ниже, поэтому некоторые шаги выполняются на более низком усилии, чем в аналогичном учебнике для 5.5.

В ходе практических шагов ниже я буду предлагать подходящий уровень рассуждения для каждой задачи, но смело экспериментируйте с настройками и смотрите, как меняется результат.

Выбор размера контекстного окна и режима скорости

Можно выбрать контекстное окно 272K или 1M и включить режим Fast, чтобы генерировать токены примерно в 1,5 раза быстрее за ~2,5-кратную стоимость кредитов. Для интерактивного диалога, когда вы ждёте ответы, Fast часто оправдан. Для длительных фоновых задач, когда вы передали работу и заняты другим, можно оставить его выключенным.

Настройка Cursor

Давайте настроим проект в Cursor.

Предварительные требования и начальная конфигурация

Для GPT-5.6 Sol требуется платный план Cursor (Pro или выше), и поскольку Sol работает в Max Mode, на аккаунте должен быть включён биллинг по использованию. Python 3.11+ — единственная дополнительная локальная зависимость для этого проекта. Если Cursor ещё не установлен, скачайте его на cursor.com, войдите в аккаунт, а затем в терминале выполните:

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

Панель агента — справа, а проводник слева пока не показывает файлов — это именно то состояние, с которого стоит стартовать, прежде чем дать агенту построить структуру.

Навигация по AI-поверхностям Cursor

Прежде чем переходить к сборке, полезно понимать три основных режима взаимодействия и когда какой использовать, потому что неверный выбор легко создаёт лишние трения.

Встроенное автодополнение — это фоновый слой подсказок. По мере набора появляются серые предложения на основе того, что вы пишете, и окружения в файле; принять — Tab. Вы его не вызываете — оно просто появляется. Этот режим уместен, когда вы пишете код вручную и хотите сократить набор без нарушения потока.

Режим Ask позволяет модели читать ваши файлы и отвечать на вопросы, не внося изменений. Представьте, что вы просите коллегу посмотреть код и сказать, что он видит. Особенно полезно в незнакомой кодовой базе, когда вы пытаетесь понять, почему что-то реализовано так, или продумываете подход до того, как на нём закрепиться.

Режим агента — движущая сила этого учебника. В сессии агент редактирует файлы, запускает команды терминала, ставит пакеты, выполняет тесты, читает вывод и замыкает цикл на сбоях — всё в одной непрерывной ветке. Это режим, где вы передаёте задачу, а не просто спрашиваете о ней, и качество результата напрямую зависит от объёма контекста, который вы дадите изначально. Переключатель режима агента видно внизу слева на скриншоте выше.

Задание проектных правил в AGENTS.md

Этот файл вы пишете сами, модель пока не используем. Сначала переключитесь на High, так как следующий промпт — момент, когда агент его прочитает. Большинство сессий с агентом идут наперекосяк не потому, что модель ошиблась, а потому что не знала чего-то проектно-специфичного и додумала: ваш фреймворк, соглашения по именованию, какие файлы нельзя трогать, как проверять изменения.

Для этого и нужен AGENTS.md: это README для агента, где вы записываете то, что для вас очевидно, а для модели невидимо. AGENTS.md начался как инициатива OpenAI в 2025 году и теперь стал кросс-инструментальным стандартом файлов инструкций для агентов (часть Agentic AI Foundation при Linux Foundation, наряду с MCP от Anthropic), так что стоит выучить один раз и применять везде.

Создайте файл AGENTS.md в корне проекта со следующим содержимым, чтобы задать стек инструментов, кодовые соглашения и границы:

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

Раздел с границами чаще всего пропускают — и напрасно: он самый важный. Без него агенты время от времени решают «помочь», переорганизуя или вычищая то, о чём вы не просили. Сказать модели, что трогать нельзя, так же полезно, как и сказать, что делать.

AGENTS.md — кросс-инструментальный стандарт, но если вы хотите нативный для Cursor аналог, который делает то же самое через scoped-файлы .mdc, наш учебник Cursor Rules показывает, как собрать набор для Python-веб-проекта.

Создание API учёта бюджета с GPT-5.5

Проект — это REST API для учёта персональных бюджетных записей. Можно создавать записи, выводить список с необязательной фильтрацией по категории, удалять записи и получать помесячную сводку расходов. 

Он достаточно прост, чтобы не утонуть в предметной области, но реализация включает слой БД, валидацию ввода, типизированные модели ответов и несколько обработчиков маршрутов, работающих вместе — этого достаточно, чтобы показать, как агент действует в реальной многофайловой сессии.

Шаг 1: Скелет проекта

Откройте панель агента и установите уровень рассуждения на High перед тем, как что-либо отправлять. План, который агент составит до написания кода, полезен ровно настолько, насколько основательно он был продуман; поверхностный ответ здесь означает структурные решения, которые потом придётся распутывать. Отправьте такой первый промпт:

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.

Последняя строка стоит того, чтобы включать её во все нетривиальные промпты агенту. Просьба показать план до исполнения занимает у вас секунд 15 на чтение, но позволяет поймать структурные решения до того, как они разойдутся по десятку файлов. 

GPT-5.6 Sol на уровне High выдаёт планы, достаточно конкретные, чтобы быть полезными, а не расплывчатые пересказы. Проверка структуры сейчас намного быстрее, чем перестройка позже.

Агент предлагает структуру проекта и ждёт подтверждения прежде, чем записать хоть один файл.

Как только вы ответите что-то вроде «Выглядит хорошо, продолжай», агент начнёт сборку. Вы увидите, как дерево файлов слева наполняется в реальном времени, а внизу в терминале uv устанавливает пакеты.

Агент создал pyproject.toml как часть скелета, а содержимое файла показано в редакторе как новое дополнение.

После завершения скелета уделите минуту и откройте app/models.py и app/database.py. Убедитесь, что у модели BudgetEntry есть как минимум поля id, amount, description, category и date, а database.py настраивает асинхронный движок SQLite без чего-то необычного. 

Если что-то выглядит странно, скажите об этом в следующем сообщении, а не продолжайте. Исправления на этом этапе дешёвы; после двадцати изменённых файлов — нет.

Шаг 2: Реализация основных эндпоинтов

Оставьте уровень на High или попробуйте Medium, поскольку Sol на Medium справляется с согласованной работой по нескольким файлам, которая в GPT-5.5 требовала High. Отправьте промпт для реализации:

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.

Агент затрагивает models.py, database.py, routers/entries.py и main.py за один согласованный проход. По мере завершения каждого файла Cursor показывает новые фрагменты в редакторе, чтобы вы могли их просмотреть до принятия. Внизу каждого изменённого файла видны элементы Undo/Keep.

На скриншоте показан роутер entries.py после реализации агентом, вместе с подтверждением, что сервер запущен и эндпоинт /docs успешно открылся. 

После принятия реализации и запуска сервера откройте http://localhost:8000/docs в браузере, чтобы убедиться, что всё корректно подключено.

Автосгенерированная документация FastAPI на /docs, где видно, что все три эндпоинта зарегистрированы корректно. 

Шаг 3: Добавление валидации категорий

На этом шаге можно снизить уровень рассуждения до Low или Medium. Добавление enum и двух тестов — задача достаточно локальная и предсказуемая, чтобы не «сжигать» на неё лишние циклы размышлений.

Сейчас API принимает любую строку как категорию, что быстро приведёт к несогласованным данным. Исправим это:

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.

Агент добавит enum категорий в models.py и обновит модель Pydantic, чтобы использовать его. Так как Pydantic автоматически валидирует по enum, неверные категории отклоняются ещё до входа в обработчик маршрута.

Он также напишет два теста: один подтверждает, что запись с корректной категорией сохраняется, другой — что некорректная получает 422.

Использование ссылки @

После принятия изменений попробуйте функцию контекста Cursor с @, чтобы задать короткий вопрос для проверки:

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

Набор @ в панели агента открывает выбор файла; после выбора app/models.py содержимое этого файла попадёт прямо в промпт, без необходимости агенту что-то искать или догадываться о пути.

Шаг 4: Эндпоинт помесячной сводки

Здесь переключитесь обратно на High. Запрос на агрегацию требует от агента совместно продумать фильтрацию, группировку и дизайн модели ответа; ошибка в любом из этих пунктов означает повторные правки во всех трёх файлах. С учётом готового CRUD добавим сводный эндпоинт:

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.

Это более интересная задача по БД, потому что требует фильтрованного запроса с агрегацией, а не простого выбора всего. Посмотрите, как агент строит запрос в database.py; он должен использовать интерфейс запросов SQLModel, а не чистый SQL, и результат должен чисто маппиться на модель ответа, определённую в models.py.

После принятия изменений напишите для этого эндпоинта один тест вручную в test_entries.py. Создайте две записи в конкретном месяце, вызовите эндпоинт сводки для этого месяца и проверьте суммы. Написание этого теста вручную — хороший способ понять, как устроены тест-клиент и фикстуры.

Файл test_entries.py показывает тесты на валидацию категорий, написанные агентом, рядом с вручную написанной функцией test_monthly_summary. 

Шаг 5: Запуск цикла валидации

Low или Medium здесь достаточно: запуск тестов и исправление линтинга — реактивная работа, агент читает ошибки и вносит точечные правки, а не принимает архитектурные решения. Передайте тестирование обратно агенту:

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.

Следите за панелью агента по мере стриминга вывода pytest. 

Если что-то падает, агент читает traceback, определяет, какой файл внёс проблему, и вносит исправление — всё в рамках одной сессии. Вам не нужно копировать ошибку в новое сообщение; весь цикл отладки и исправления идёт в одной непрерывной нити.

На скриншоте агент отчитывается после полного цикла валидации. В данном случае проверка ruff наткнулась на проблему с определением интерпретатора из-за несоответствия pyenv/.python-version на локальной машине — это не проблема кода. 

Важно заметить, что произошло: агент столкнулся с проблемой окружения, не связанной с нашим кодом, разобрался с причиной и нашёл обходной путь без дополнительных подсказок. Такой контекстный подход к решению проблем, включая сбои инструментов, — именно то, в чём GPT-5.6 Sol заметно обгоняет более ранние модели.

Также полезно включать «не изменяйте утверждения тестов ради прохождения» в каждый промпт для валидации. Без этой оговорки агенты иногда идут по пути наименьшего сопротивления и ослабляют проверку теста вместо исправления поведения.

Шаг 6: Проход код-ревью

Перед отправкой поставьте уровень обратно на High или выберите Extra High/Max, если хотите, чтобы Sol основательно прошлась по краевым случаям, которые один проход на High может пропустить. На этом шаге поверхностное рассуждение создаёт ложное чувство безопасности; вы хотите, чтобы модель действительно проработала все потенциальные вопросы, а не только сопоставила шаблоны с очевидными.

Перед тем как считать проект завершённым, используйте агента для обзора:

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.

Агент обнаружил, что DELETE /api/v1/entries/{entry_id} корректно возвращает коды 204 и 404 (с указанием file:line), что для GET-маршрутов корректны дефолты 200, и подтвердил, что пользовательский ввод не попадает в БД в обход ORM.

После просмотра списка отправьте запрос на применение исправлений:

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.

Шаг 7: README и CI workflow

Два завершающих штриха. Для обоих можно снизить уровень рассуждения до Low. Структура README предсказуема, а YAML для CI по сути типовой — здесь нечего продумывать, и платить за высокий уровень размышлений нет смысла.

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

Затем:

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

После всех семи шагов структура проекта выглядит так:

Заключение

Мы собрали небольшой API, но сам рабочий процесс масштабируется на что угодно. 

Подготовьте AGENTS.md до того, как агент тронет хоть один файл. Запрашивайте план перед выполнением для всего нетривиального. Разбивайте промпты на этапы, чтобы иметь естественные контрольные точки, а не один гигантский diff для обзора. Используйте @filename, когда хотите задать прицельный вопрос по конкретному файлу. И делайте проход обзора, прежде чем считать задачу завершённой — почти всегда что-то найдётся.

GPT-5.6 Sol в Cursor заметно лучше прежних сочетаний в умении держать фокус на задаче в длинных сессиях, ловить межфайловые несогласованности и вовремя останавливаться, чтобы уточнить, а не нестись вперёд, делая разрушительные вещи. Но модель — лишь часть картины. Контекст, который вы даёте изначально, циклы проверки и проход обзора в конце — вот где происходит реальное улучшение качества результата.

Хорошее правило по уровням рассуждения: используйте High для архитектурных решений, координации нескольких файлов и отладки неочевидных проблем; используйте Medium или Low для документации, шаблонного кода и правок в одном файле, где вы по сути просите модель «набирать текст». Рассматривайте Extra High или Max для код-ревью и там, где ошибки дороже, чем обстоятельный прогон агента.