Tutorial do modo Agent do Cursor: construindo uma REST API com o GPT-5.6 Sol

O que é o Cursor?

Cursor nasceu como um VS Code com recursos de IA integrados, e ainda parece isso à primeira vista. O editor, a árvore de arquivos, o terminal, as extensões — tudo familiar. 

O que foi refeito por baixo dos panos é a premissa de que a IA não está só respondendo perguntas de lado, mas trabalhando com você de fato. É por isso que você tem o modo agent, indexação do codebase, um seletor de modelos para alternar entre modelos de ponta no meio da sessão e autocompletes inline que preveem seu próximo passo com base no contexto completo do que você vem fazendo.

Se quiser explorar mais os recursos mais novos do Cursor, recomendo ler nossos tutoriais sobre Cursor Automations e Cursor SDK.

O que é o GPT-5.6?

GPT-5.6 é a geração mais recente da OpenAI — e não é um único modelo, mas três: Sol, Terra e Luna. Esses nomes representam três níveis distintos de capacidade, substituindo o antigo rótulo "Instant".

Um resumo da família:

• Sol é o carro-chefe e o mais forte dos três. É o único nível que libera o novo esforço de raciocínio max e o modo ultra, e é onde os ganhos em programação, biologia e cibersegurança são maiores.

• Terra é o padrão do dia a dia. A OpenAI o posiciona como competitivo com o GPT-5.5 por cerca de metade do preço.

• Luna é o nível rápido e econômico para trabalho de alto volume ou sensível à latência — e é mais forte do que o preço sugere.

Para um passo a passo de código, Sol é o nível que importa — então é o que usamos aqui. Duas configurações no Sol são novas, e vale saber qual você realmente vai usar. max é um esforço de raciocínio acima de xhigh que permite a um único agente gastar mais tempo em um problema difícil, e é o topo da escada que você define no Cursor. Já o ultra, que divide o trabalho em subagentes paralelos, publica os melhores números de benchmark da OpenAI (91,9% no Terminal-Bench 2.1), mas roda só no Codex e na API — então você não vai encontrá-lo no seletor do Cursor.

Para a tabela completa de benchmarks e os preços dos três níveis, confira nosso guia de GPT-5.6 Sol, Terra e Luna.

Como acessar e configurar o GPT-5.6 Sol no Cursor

GPT-5.6 Sol está disponível no seletor de modelos do Cursor, e há um ponto importante logo de cara: como outros modelos de fronteira recentes no Cursor, o Sol roda apenas no Max Mode do Cursor. Isso significa que ele usa toda a janela de contexto e todas as ferramentas, e a cobrança é por uso, não por requisição — então fique de olho no gasto de tokens em execuções longas.

Para selecionar o modelo:

1. Abra o painel do agente com Cmd+L (Mac) ou Ctrl+L (Windows/Linux).
2. Clique no botão Model na parte inferior da área de entrada (ele mostra o nome do modelo atual ao lado de um ícone pequeno).
3. Desative o Auto se ele estiver ligado.
4. Encontre o GPT-5.6 Sol na lista e clique em Edit ao lado dele.
5. Um painel se abre à direita, onde você pode ajustar de forma independente a janela de contexto, o nível de raciocínio e o modo rápido.

Escolhendo o esforço de raciocínio certo

Selecionar o Sol escolhe o modelo; o esforço de raciocínio decide o quanto ele pensa em uma tarefa específica. Você pode escolher entre:

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

None e Low são as mais rápidas e baratas — ótimas para autocomplete ou um refactor mecânico em que você já sabe o que quer. 

High e Extra High demoram mais porque realmente pensam no problema antes — e você percebe essa diferença sobretudo quando pede ao agente para planejar algo que cruza vários arquivos ou depurar uma falha cujo motivo não está evidente.

Max fica acima de Extra High e dá a um único agente o máximo de tempo para trabalhar em um problema difícil. O modo multiagente ultra do Sol existe apenas no Codex e na API, então você não vai vê-lo no seletor do Cursor.

Um aviso para quem vem do GPT-5.5: os níveis não mapeiam de forma direta. A própria OpenAI orienta começar um nível abaixo do que você usava em uma tarefa conhecida e só aumentar se o resultado pedir. Sigo isso abaixo — então algumas etapas rodam com esforço menor do que no tutorial equivalente do 5.5.

Ao longo dos passos práticos abaixo, vou sugerir o nível de raciocínio mais adequado para cada tarefa — mas sinta-se à vontade para experimentar e ver como a saída muda.

Escolhendo o tamanho da janela de contexto e o modo de velocidade

Você também pode escolher entre janelas de contexto de 272K e 1M, e ativar o modo Fast para gerar tokens ~1,5x mais rápido por cerca de 2,5x o custo em créditos. Em interações de ida e volta, em que você espera respostas, Fast geralmente compensa. Em tarefas mais longas em segundo plano, nas quais você delega algo e faz outras coisas enquanto roda, pode deixar desligado sem problemas.

Configurando o Cursor

Vamos preparar o projeto no Cursor.

Pré-requisitos e configuração inicial

É necessário um plano pago do Cursor (Pro ou superior) para usar o GPT-5.6 Sol e, como o Sol roda em Max Mode, a cobrança por uso precisa estar habilitada na sua conta. Python 3.11+ é a única dependência local de que você precisa para este projeto. Se o Cursor não está instalado ainda, baixe em cursor.com, faça login e, no terminal:

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

O painel do Agent fica à direita, e o explorador de arquivos à esquerda ainda não mostra nada — exatamente como você quer começar antes de deixar o agente montar a estrutura.

Navegando pelas superfícies de IA do Cursor

Antes de entrar na construção em si, vale entender quais são os três principais modos de interação e quando cada um faz sentido — usar o modo errado cria atritos fáceis de evitar.

Autocompletar inline é a camada de autocomplete em segundo plano. Conforme você digita, surgem sugestões acinzentadas com base no que você está escrevendo e no contexto ao redor no arquivo. Você aceita com Tab. Você não invoca: elas simplesmente aparecem. É o modo certo quando você está escrevendo código à mão e quer reduzir teclas sem interromper seu fluxo.

Ask mode é onde o modelo lê seus arquivos e responde perguntas sem fazer alterações. Pense em pedir a um colega para olhar o código e te dizer o que vê. É particularmente útil em um codebase novo, quando você tenta entender por que algo foi escrito de um certo jeito ou só quer amadurecer uma abordagem antes de se comprometer com ela.

Agent mode é o que move este tutorial inteiro. Em uma sessão de agente, o modelo edita arquivos, roda comandos de terminal, instala pacotes, executa sua suíte de testes, lê a saída e faz o ciclo de volta em falhas — tudo dentro de uma única thread contínua. É o modo em que você passa a tarefa adiante, não só pergunta sobre ela — e a qualidade do que você recebe escala diretamente com o contexto que você dá logo de início. Você vê o seletor do Agent mode no canto inferior esquerdo do painel, na captura acima.

Definindo orientações específicas do projeto com o AGENTS.md

Você vai escrever este arquivo à mão, sem modelo por enquanto. Troque para High primeiro, já que o próximo prompt é quando o agente o lê. A maioria das sessões com agente desanda não porque o modelo errou, mas porque não sabia algo específico do projeto e chutou: seu framework, suas convenções de nomenclatura, quais arquivos são proibidos, como validar mudanças.

É para isso que serve o AGENTS.md: um README para o agente, onde você anota o que é óbvio para você, mas invisível para o modelo. O AGENTS.md começou como uma iniciativa da OpenAI em 2025 e hoje é o padrão entre ferramentas para arquivos de instrução de agentes (parte da Agentic AI Foundation da Linux Foundation, ao lado do MCP da Anthropic), então vale a pena aprender uma vez e usar sempre.

Crie um arquivo chamado AGENTS.md na raiz do projeto com o seguinte conteúdo para definir sua stack de ferramentas, convenções de código e limites:

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

A seção de limites é a que as pessoas mais pulam — e é a mais importante. Sem ela, às vezes os agentes decidem "ajudar" reorganizando ou limpando coisas que você não pediu para mexer. Dizer ao modelo o que é proibido é tão útil quanto dizer o que fazer.

AGENTS.md é o padrão entre ferramentas, mas se você quiser o equivalente nativo do Cursor que faz o mesmo via arquivos .mdc com escopo, nosso tutorial Cursor Rules mostra como montar um conjunto para um projeto web em Python.

Construindo uma API de orçamento com o GPT-5.5

O projeto é uma REST API para registrar despesas pessoais. Você pode criar lançamentos, listá-los com filtro opcional por categoria, excluí-los e obter um resumo mensal de gastos. 

É simples o bastante para acompanhar sem se perder na lógica de domínio, mas envolve camada de banco, validação de entrada, modelos de resposta tipados e vários handlers de rota trabalhando juntos — o suficiente para mostrar o que o agente realmente faz em uma sessão real com vários arquivos.

Passo 1: criar o esqueleto do projeto

Abra o painel do agente e defina o esforço de raciocínio como High antes de enviar qualquer coisa. O plano que o agente produz antes de escrever código só é útil na medida do raciocínio por trás dele — uma resposta rasa aqui vira decisões estruturais que você vai ter que desfazer depois. Envie este primeiro 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.

Essa última linha vale manter em todos os prompts de agente que não são triviais. Pedir o plano antes da execução custa uns 15 segundos de leitura, mas deixa você pegar decisões estruturais antes de se espalharem por uma dúzia de arquivos. 

O GPT-5.6 Sol em High gera planos específicos o suficiente para serem úteis — não resumos vagos — e revisar a estrutura agora é muito mais rápido do que reorganizar depois.

O agente propõe o layout do projeto e aguarda aprovação antes de escrever um único arquivo.

Quando você responder algo como "Parece bom, pode seguir", o agente começa a construir. Dá para ver a árvore de arquivos à esquerda sendo populada em tempo real, enquanto o terminal embaixo mostra o uv instalando os pacotes.

O agente criou um pyproject.toml como parte do esqueleto, com o conteúdo do arquivo mostrado como nova adição.

Depois que o esqueleto terminar, reserve um minuto para abrir o app/models.py e o app/database.py antes de seguir. Confirme se o modelo BudgetEntry tem ao menos os campos id, amount, description, category e date, e se o database.py configura o engine assíncrono do SQLite sem nada fora do comum. 

Se algo parecer estranho, diga logo na próxima mensagem em vez de continuar. Correções nesta etapa são baratas; depois que vinte arquivos forem modificados, não são.

Passo 2: implementar os endpoints principais

Mantenha o esforço em High, ou teste Medium primeiro — o Sol em Medium dá conta de trabalho coordenado entre vários arquivos que no GPT-5.5 exigiria High. Envie o prompt de implementação:

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.

O agente mexe em models.py, database.py, routers/entries.py e main.py em uma passada coordenada. Conforme conclui cada arquivo, o Cursor destaca o conteúdo novo no editor para você revisar antes de aceitar. Você verá os controles Undo/Keep no rodapé de cada arquivo alterado.

A captura mostra o router entries.py após a implementação pelo agente, junto com a confirmação de que o servidor iniciou e que o endpoint /docs carregou corretamente. 

Com a implementação aceita e o servidor no ar, abra http://localhost:8000/docs no navegador para confirmar que está tudo ligado certinho.

A documentação gerada automaticamente do FastAPI em /docs, mostrando os três endpoints registrados corretamente. 

Passo 3: adicionar validação de categoria

Nesta terceira etapa, você pode reduzir o raciocínio do modelo para Low ou Medium. Adicionar um enum e dois testes é auto-contido e previsível, não precisa gastar ciclos extra de deliberação aqui. 

Hoje, a API aceita qualquer string como categoria — o que leva rápido a dados inconsistentes. Vamos corrigir:

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.

O agente vai adicionar um enum de categoria em models.py e atualizar o modelo do Pydantic para usá-lo. Como o Pydantic valida automaticamente contra o enum, categorias inválidas são rejeitadas antes mesmo do handler de rota rodar.

Ele também deve escrever dois testes: um confirmando que uma categoria válida salva corretamente e outro confirmando que uma inválida retorna 422.

Usando a referência @

Depois de aceitar as mudanças, experimente o recurso de contexto @ do Cursor para fazer uma verificação rápida:

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

Ao digitar @ no painel do agente, abre-se um seletor de arquivos — e, ao escolher app/models.py, o conteúdo desse arquivo vai direto para o prompt, sem o agente precisar procurar ou supor o caminho.

Passo 4: construir o endpoint de resumo mensal

Volte para High aqui. A consulta de agregação exige que o agente raciocine sobre filtragem, agrupamento e o design do modelo de resposta juntos — errar qualquer um deles implica mexer nos três arquivos de novo. Com o CRUD principal funcionando, adicione o endpoint de resumo:

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 é uma tarefa de banco mais interessante porque requer uma consulta filtrada com agregação, não um select-all simples. Observe como o agente estrutura a consulta em database.py; ele deve usar a interface de consulta do SQLModel em vez de SQL cru, e o resultado deve mapear corretamente para o modelo de resposta definido em models.py.

Depois de aceitar as mudanças, escreva você mesmo um teste para esse endpoint em test_entries.py. Crie duas entradas em um mês específico, chame o endpoint de resumo para esse mês e verifique se os totais batem. Escrever este manualmente é uma boa forma de se familiarizar com o test client e os fixtures.

O arquivo test_entries.py mostra os testes de validação de categoria escritos pelo agente ao lado da função test_monthly_summary escrita manualmente. 

Passo 5: rodar o loop de validação

Low ou Medium funcionam bem aqui — rodar testes e corrigir lint é trabalho reativo: o agente lê a saída de erro e aplica correções pontuais, sem tomar decisões arquiteturais de verdade. Devolva os testes ao 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.

Acompanhe no painel do agente a saída do pytest. 

Se algo falhar, o agente lê o traceback, identifica qual arquivo introduziu o problema e aplica a correção — tudo na mesma sessão. Você não precisa copiar e colar o erro em uma nova mensagem; o loop completo de depuração e correção acontece em uma única thread contínua.

A captura mostra o agente reportando após o loop completo de validação. Neste caso, o ruff esbarrou em um problema de resolução do interpretador causado por um desencontro de pyenv/.python-version na máquina local — não um problema de código. 

Vale notar o que aconteceu: o agente enfrentou um problema de ambiente, não relacionado ao código que escrevemos, raciocinou sobre a causa e encontrou uma alternativa — sem ser provocado. Esse tipo de resolução contextual através de falhas de ferramenta é exatamente onde o GPT-5.6 Sol se destaca em relação a modelos anteriores.

Também vale incluir "não modifique asserções de teste para fazê-las passar" em todo prompt de validação que você escrever. Sem essa instrução, às vezes os agentes seguem o caminho de menor resistência e enfraquecem o que o teste verifica, em vez de corrigir o comportamento real.

Passo 6: passagem de code review

Volte o raciocínio para High antes de enviar este, ou Extra High/Max se quiser que o Sol esmiúce casos de borda que um único High pode passar por cima. Nesta etapa, raciocínio raso cria uma falsa segurança; você quer que o modelo realmente percorra todos os pontos potenciais, não só faça pattern-match nos mais óbvios. 

Antes de dar o projeto por encerrado, use o agente para uma revisão:

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.

O agente constatou que o DELETE /api/v1/entries/{entry_id} retorna corretamente os códigos 204 e 404 (com referências arquivo:linha), que as rotas GET usam os 200 corretos por padrão e confirmou que nenhuma entrada do usuário chega ao banco fora do ORM.

Depois de revisar a lista, envie o follow-up para aplicar as correções:

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.

Passo 7: README e workflow de CI

Dois toques finais para fechar o projeto do jeito certo. Você pode reduzir o raciocínio do modelo para Low em ambos. A estrutura do README é previsível, e o YAML de CI é praticamente boilerplate — não há nada a raciocinar aqui; pagar por raciocínio alto seria desperdício de créditos.

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

E depois:

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

Após os sete passos, a estrutura do projeto fica assim:

Considerações finais

O que construímos aqui é uma API pequena, mas o fluxo escala para qualquer coisa. 

Coloque o AGENTS.md no lugar antes do agente tocar em um único arquivo. Peça o plano antes de executar em qualquer coisa não trivial. Estruture seus prompts em etapas, para ter checkpoints naturais em vez de um diff gigante para revisar de uma vez. Use @filename quando quiser perguntar algo pontual sobre um arquivo específico. E rode uma passagem de revisão antes de considerar a tarefa concluída — quase sempre aparece algo.

O GPT-5.6 Sol no Cursor é visivelmente melhor do que combinações anteriores em manter o foco em sessões longas, captar inconsistências entre arquivos e saber quando pausar e checar em vez de avançar de forma destrutiva. Mas o modelo é só parte do resultado. O contexto que você dá no início, os loops de validação que roda e a passagem de revisão no fim — é aí que está a verdadeira melhora na qualidade.

Uma boa regra para níveis de raciocínio: use High para decisões de arquitetura, coordenação entre vários arquivos e depuração de algo não óbvio; use Medium ou Low para documentação, boilerplate e edições de um arquivo só, em que você só quer que o modelo digite por você. Considere Extra High ou Max para code reviews e situações em que erros custam mais do que uma passada caprichada do agente.