Hướng dẫn Agent Mode của Cursor: Xây dựng REST API với GPT-5.6 Sol

Cursor là gì?

Cursor khởi đầu là VS Code với các tính năng AI ghép vào, và bề ngoài trông vẫn như vậy. Trình soạn thảo, cây tệp, terminal, extensions—tất cả đều quen thuộc.

Phần được xây dựng lại bên dưới là giả định rằng AI không chỉ trả lời bên lề mà thực sự làm việc cùng bạn, đó là lý do có chế độ agent, lập chỉ mục codebase, bộ chọn mô hình cho phép hoán đổi giữa các mô hình hàng đầu ngay giữa phiên, và gợi ý nội tuyến dự đoán bước tiếp theo dựa trên toàn bộ ngữ cảnh công việc bạn đang làm.

Nếu bạn muốn khám phá sâu hơn các tính năng mới nhất của Cursor, tôi khuyên đọc các hướng dẫn về Cursor Automations và Cursor SDK.

GPT-5.6 là gì?

GPT-5.6 là thế hệ mô hình mới nhất của OpenAI, và không chỉ có một mô hình mà là ba: Sol, Terra và Luna. Những tên gọi này tương ứng với ba bậc năng lực riêng biệt, thay thế nhãn "Instant" cũ.

Tóm tắt họ mô hình:

• Sol là mẫu hàng đầu và mạnh nhất trong ba mẫu. Đây là cấp duy nhất mở khóa mức nỗ lực suy luận max và chế độ ultra mới, và là nơi có các cải tiến lớn nhất về lập trình, sinh học và an ninh mạng.

• Terra là mặc định hằng ngày. OpenAI định vị nó cạnh tranh với GPT-5.5 với chi phí khoảng một nửa.

• Luna là cấp nhanh, rẻ cho khối lượng lớn hoặc công việc nhạy độ trễ, và mạnh hơn so với mức giá.

Cho phần hướng dẫn lập trình, Sol là cấp quan trọng, vì vậy chúng ta dùng nó ở đây. Hai thiết lập mới trên Sol đáng để biết bạn sẽ thực sự dùng cái nào. max là mức nỗ lực suy luận cao hơn xhigh cho phép một agent dành nhiều thời gian hơn cho một vấn đề khó, và đây là nấc cao nhất bạn đặt trong Cursor. ultra, phân chia công việc qua các subagent song song, đạt điểm benchmark tốt nhất của OpenAI (91.9% trên Terminal-Bench 2.1) nhưng chỉ chạy trong Codex và API, nên bạn sẽ không thấy trong bộ chọn của Cursor.

Để xem đầy đủ bảng benchmark và giá theo ba cấp, hãy xem hướng dẫn GPT-5.6 Sol, Terra và Luna của chúng tôi.

Cách truy cập và cấu hình GPT-5.6 Sol trong Cursor

GPT-5.6 Sol có trong bộ chọn mô hình của Cursor, và có một điều cần biết trước: như các mô hình frontier gần đây khác của Cursor, Sol chỉ chạy trong Max Mode của Cursor. Điều đó nghĩa là nó dùng toàn bộ cửa sổ ngữ cảnh và mọi công cụ, và được tính phí theo mức sử dụng thay vì mỗi yêu cầu, vì vậy hãy để ý chi tiêu token trong các phiên chạy dài.

Để chọn mô hình:

1. Mở bảng agent với Cmd+L (Mac) hoặc Ctrl+L (Windows/Linux).
2. Nhấp nút Model ở dưới vùng nhập (nút hiển thị tên mô hình hiện tại cạnh một biểu tượng nhỏ).
3. Tắt Auto nếu đang bật.
4. Tìm GPT-5.6 Sol trong danh sách và nhấp Edit bên cạnh.
5. Bảng bên phải mở ra, nơi bạn có thể đặt độc lập cửa sổ ngữ cảnh, mức suy luận, và chuyển đổi chế độ nhanh.

Chọn mức nỗ lực suy luận phù hợp

Chọn Sol là chọn mô hình; mức nỗ lực suy luận quyết định mô hình "nghĩ" kỹ đến đâu cho một tác vụ. Bạn có thể chọn giữa:

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

None và Low là nhanh và rẻ nhất, đủ tốt cho công việc autocomplete hoặc refactor mang tính cơ học khi bạn cơ bản đã biết mình muốn gì.

High và Extra High mất thời gian hơn vì chúng thực sự nghĩ qua vấn đề trước, và bạn sẽ thấy khác biệt rõ khi yêu cầu agent lập kế hoạch cho tác vụ chạm vào nhiều tệp hoặc gỡ lỗi một lỗi mà nguồn gốc không hiển nhiên.

Max ở trên Extra High và cho một agent nhiều thời gian nhất để xử lý một vấn đề khó. Chế độ đa agent ultra của Sol chỉ có trong Codex và API, nên bạn sẽ không thấy trong bộ chọn của Cursor.

Một lưu ý nếu bạn chuyển từ GPT-5.5: các mức không tương ứng trực tiếp. Hướng dẫn của chính OpenAI là bắt đầu thấp hơn một mức so với bạn thường dùng cho tác vụ quen thuộc và chỉ tăng nếu kết quả cần. Tôi đã làm theo bên dưới, nên một vài bước này chạy ở mức nỗ lực thấp hơn so với hướng dẫn tương đương cho 5.5.

Xuyên suốt các bước thực hành bên dưới, tôi sẽ gợi ý mức suy luận hợp lý cho mỗi tác vụ, nhưng bạn cứ thoải mái thử các thiết lập khác nhau để xem kết quả thay đổi ra sao.

Chọn kích thước cửa sổ ngữ cảnh và chế độ tốc độ

Bạn cũng có thể chọn giữa cửa sổ ngữ cảnh 272K và 1M, và bật chế độ Fast để tạo token nhanh hơn khoảng 1.5x với chi phí tín dụng khoảng 2.5x. Với tương tác qua lại khi bạn đợi phản hồi, Fast thường đáng dùng. Với tác vụ nền dài hơn khi bạn giao việc và làm việc khác trong lúc chạy, để tắt cũng ổn.

Thiết lập Cursor

Hãy thiết lập dự án trong Cursor.

Điều kiện tiên quyết và cấu hình ban đầu

Bạn cần gói Cursor trả phí (Pro hoặc cao hơn) để dùng GPT-5.6 Sol, và vì Sol chạy trong Max Mode, thanh toán theo mức sử dụng cần được bật trong tài khoản của bạn. Python 3.11+ là phụ thuộc cục bộ duy nhất bạn cần cho dự án này. Nếu Cursor chưa được cài đặt, tải tại cursor.com, đăng nhập, rồi từ terminal:

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

Bảng Agent ở bên phải, và trình duyệt tệp bên trái chưa có tệp nào—đúng như bạn muốn khi bắt đầu trước khi để agent xây dựng cấu trúc.

Điều hướng các bề mặt AI của Cursor

Trước khi bắt tay vào xây dựng, đáng để biết ba chế độ tương tác chính là gì và khi nào dùng mỗi chế độ, vì dùng sai sẽ tạo ma sát có thể tránh được.

Gợi ý nội tuyến là lớp autocomplete nền. Khi bạn gõ, các gợi ý mờ hiện ra dựa trên những gì bạn viết và ngữ cảnh xung quanh trong tệp, và bạn chấp nhận bằng phím Tab. Bạn không cần gọi nó; nó tự hiện. Đây là chế độ phù hợp khi bạn tự viết code và muốn mô hình giảm số lần gõ mà không làm gián đoạn dòng chảy.

Chế độ Hỏi là nơi bạn có thể để mô hình đọc tệp và trả lời câu hỏi mà không thực hiện thay đổi. Hãy coi như bạn nhờ đồng nghiệp xem code và cho biết họ thấy gì. Đặc biệt hữu ích khi bạn ở trong codebase lạ, cố hiểu vì sao thứ gì đó viết theo cách nhất định, hoặc đang suy nghĩ một hướng tiếp cận trước khi cam kết.

Chế độ Agent là động lực cho toàn bộ hướng dẫn này. Trong một phiên agent, mô hình chỉnh sửa tệp, chạy lệnh terminal, cài gói, thực thi bộ kiểm thử, đọc kết quả và lặp lại khi lỗi, tất cả trong một mạch liên tục. Đây là chế độ bạn giao phó một tác vụ chứ không chỉ hỏi, và chất lượng kết quả tỉ lệ thuận với lượng ngữ cảnh bạn đưa ngay từ đầu. Bạn có thể thấy bộ chọn Agent mode ở góc dưới bên trái của bảng trong ảnh chụp ở trên.

Thiết lập hướng dẫn theo dự án với AGENTS.md

Bạn sẽ tự viết tệp này, nên chưa dùng mô hình. Chuyển sang High trước, vì prompt tiếp theo là lúc agent đọc nó. Phần lớn phiên agent trật hướng không phải do mô hình sai, mà vì nó không biết điều gì đó đặc thù của dự án và đoán: framework của bạn, quy ước đặt tên, tệp nào không được đụng, cách xác minh thay đổi.

Đó là lý do có AGENTS.md: một README cho agent, nơi bạn viết xuống những điều hiển nhiên với bạn nhưng vô hình với mô hình. AGENTS.md khởi nguồn là một sáng kiến của OpenAI vào năm 2025 và nay là tiêu chuẩn xuyên công cụ cho tệp hướng dẫn agent (thuộc Agentic AI Foundation của Linux Foundation, bên cạnh MCP của Anthropic), nên xứng đáng học một lần để dùng ở mọi nơi.

Tạo tệp tên AGENTS.md ở thư mục gốc dự án với nội dung sau để thiết lập ngăn xếp công cụ dự án, quy ước code và ranh giới:

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

Phần ranh giới là chỗ mọi người hay bỏ qua nhất, mà cũng quan trọng nhất. Thiếu nó, đôi khi agent sẽ "giúp" bằng cách tổ chức lại hay dọn dẹp những thứ bạn không yêu cầu. Nói cho mô hình biết điều gì là cấm đụng cũng hữu ích như bảo nó làm gì.

AGENTS.md là tiêu chuẩn xuyên công cụ, nhưng nếu bạn muốn bản tương đương gốc Cursor làm cùng việc thông qua các tệp .mdc theo phạm vi, hướng dẫn Cursor Rules của chúng tôi sẽ hướng dẫn xây dựng bộ quy tắc cho một dự án web Python.

Xây dựng Budget Tracker API với GPT-5.5

Dự án là một REST API theo dõi các khoản chi tiêu cá nhân. Bạn có thể tạo mục, liệt kê với tùy chọn lọc theo danh mục, xóa, và lấy tổng kết chi tiêu hàng tháng.

Đủ đơn giản để theo dõi mà không lạc trong logic miền, nhưng triển khai gồm lớp cơ sở dữ liệu, xác thực đầu vào, các mô hình phản hồi có kiểu và vài bộ xử lý tuyến cùng hoạt động—đủ để cho thấy agent thực sự làm gì trong một phiên đa tệp thực tế.

Bước 1: Tạo khung cấu trúc dự án

Mở bảng agent và đặt mức suy luận thành High trước khi gửi bất kỳ thứ gì. Kế hoạch agent tạo trước khi viết code chỉ hữu ích tương xứng với lý do đằng sau; câu trả lời hời hợt ở giai đoạn này dẫn đến các quyết định cấu trúc mà bạn sẽ phải gỡ sau này. Tiếp tục bằng cách gửi prompt đầu tiên sau:

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.

Dòng cuối đáng giữ trong mọi prompt agent không tầm thường. Yêu cầu kế hoạch trước khi thực thi khiến bạn tốn chừng 15 giây đọc, nhưng cho phép bắt các quyết định cấu trúc trước khi chúng lan ra cả chục tệp.

GPT-5.6 Sol ở mức High tạo kế hoạch đủ cụ thể để hữu dụng thật sự chứ không chỉ là tóm tắt mơ hồ, và rà soát cấu trúc bây giờ nhanh hơn nhiều so với tái tổ chức sau.

Agent đề xuất bố cục dự án và chờ phê duyệt trước khi viết một tệp nào.

Khi bạn trả lời kiểu "Ổn rồi, làm đi", agent bắt đầu xây dựng. Bạn có thể xem cây tệp bên trái được lấp đầy theo thời gian thực khi nó tạo tệp, trong khi terminal phía dưới hiển thị uv đang cài gói.

Agent tạo pyproject.toml như một phần của scaffold, với nội dung tệp được hiển thị như bổ sung mới.

Sau khi scaffold xong, dành một phút mở app/models.py và app/database.py trước khi đi tiếp. Xác nhận mô hình BudgetEntry có tối thiểu các trường id, amount, description, category và date, và database.py thiết lập engine SQLite bất đồng bộ mà không có gì bất thường.

Nếu thấy có gì sai, hãy nói trong tin nhắn tiếp theo thay vì tiếp tục. Sửa ở giai đoạn này rẻ; sau khi hai chục tệp bị sửa thì không còn rẻ nữa.

Bước 2: Triển khai các endpoint cốt lõi

Giữ mức nỗ lực ở High, hoặc thử Medium trước, vì Sol ở mức Medium xử lý công việc phối hợp đa tệp mà trước đây với GPT-5.5 cần High. Gửi prompt triển khai:

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 chạm vào models.py, database.py, routers/entries.py và main.py trong một lượt phối hợp. Khi hoàn tất mỗi tệp, Cursor hiển thị nội dung mới được highlight trong trình soạn thảo để bạn rà soát trước khi chấp nhận. Bạn sẽ thấy nút Undo/Keep ở dưới mỗi tệp thay đổi.

Ảnh chụp cho thấy router entries.py sau khi agent triển khai, cùng xác nhận của agent rằng máy chủ đã khởi động và endpoint /docs tải thành công.

Khi chấp nhận triển khai và máy chủ chạy, mở http://localhost:8000/docs trong trình duyệt để xác nhận mọi thứ đã nối đúng.

Tài liệu tự động của FastAPI tại /docs, hiển thị cả ba endpoint đã đăng ký đúng.

Bước 3: Thêm xác thực danh mục

Ở bước này, bạn có thể giảm mức suy luận xuống Low hoặc Medium. Việc thêm enum và hai bài test đủ độc lập và có thể tiên liệu nên không cần mô hình tốn thêm chu kỳ cân nhắc.

Hiện tại, API chấp nhận mọi chuỗi làm danh mục, dẫn đến dữ liệu thiếu nhất quán khá nhanh. Hãy sửa:

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 sẽ thêm enum danh mục vào models.py và cập nhật mô hình Pydantic để sử dụng enum đó. Vì Pydantic tự động xác thực theo enum, danh mục không hợp lệ bị từ chối trước khi handler tuyến chạy.

Nó cũng nên viết hai bài test đi kèm: một xác nhận danh mục hợp lệ được lưu đúng, một xác nhận danh mục không hợp lệ trả về 422.

Sử dụng tham chiếu @

Sau khi chấp nhận các thay đổi đó, thử tính năng ngữ cảnh @ của Cursor để hỏi nhanh một câu xác minh:

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

Gõ @ trong bảng agent mở bộ chọn tệp, và khi chọn app/models.py, nội dung tệp đó được đưa trực tiếp vào prompt mà không cần agent phải tìm kiếm hay đoán đường dẫn.

Bước 4: Xây dựng endpoint tổng kết theo tháng

Chuyển lại sang High ở đây. Truy vấn tổng hợp yêu cầu agent suy luận về lọc, nhóm và thiết kế mô hình phản hồi cùng lúc; sai một phần sẽ phải chạm lại cả ba tệp. Khi CRUD cốt lõi đã hoạt động, thêm endpoint tổng kết:

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.

Đây là tác vụ cơ sở dữ liệu thú vị hơn vì yêu cầu truy vấn có lọc và tổng hợp thay vì select-all đơn thuần. Hãy xem agent cấu trúc truy vấn trong database.py thế nào; nó nên dùng giao diện truy vấn của SQLModel thay vì SQL thô, và kết quả phải ánh xạ gọn gàng vào mô hình phản hồi được định nghĩa trong models.py.

Sau khi chấp nhận thay đổi, tự viết một bài test cho endpoint này trong test_entries.py. Tạo hai mục trong một tháng cụ thể, gọi endpoint tổng kết cho tháng đó, và assert tổng khớp. Viết tay bài này thay vì nhờ agent là cách tốt để bạn quen với cấu trúc test client và fixtures.

Tệp test_entries.py hiển thị các bài test xác thực danh mục do agent viết cùng hàm test_monthly_summary viết thủ công.

Bước 5: Chạy vòng lặp xác thực

Low hoặc Medium hoạt động tốt ở đây; chạy test và sửa lint là công việc phản ứng—agent đọc lỗi và áp dụng sửa chữa có mục tiêu thay vì quyết định kiến trúc thực sự. Giao việc kiểm thử lại cho agent:

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.

Theo dõi bảng agent khi nó stream đầu ra pytest.

Nếu có lỗi, agent đọc traceback, xác định tệp gây vấn đề và áp dụng sửa, tất cả trong cùng một phiên. Bạn không cần copy-paste lỗi vào tin nhắn mới; toàn bộ vòng gỡ lỗi và sửa xảy ra trong một mạch liên tục.

Ảnh chụp cho thấy agent báo cáo sau toàn bộ vòng xác thực. Trong trường hợp này, ruff gặp vấn đề phân giải trình thông dịch do lệch pyenv/.python-version trên máy cục bộ, không phải vấn đề code.

Đáng chú ý là điều đã xảy ra: agent gặp sự cố môi trường không liên quan đến code chúng ta viết, suy luận nguyên nhân và tìm cách xử lý mà không cần nhắc. Loại giải quyết vấn đề theo ngữ cảnh qua lỗi công cụ như vậy là chỗ GPT-5.6 Sol vượt trội hơn các mô hình trước.

Cũng nên luôn thêm "do not modify test assertions to make them pass" trong mọi prompt xác thực bạn viết. Thiếu chỉ dẫn đó, đôi khi agent chọn đường dễ nhất và làm suy yếu điều test kiểm tra thay vì sửa đúng hành vi.

Bước 6: Lượt rà soát code

Đặt suy luận về lại High trước khi gửi, hoặc Extra High/Max nếu bạn muốn Sol nghiền ngẫm các góc cạnh mà một lượt High đơn có thể lướt qua. Ở bước này, suy luận hời hợt tạo cảm giác an toàn giả; bạn muốn mô hình thực sự xem hết các vấn đề tiềm tàng, không chỉ khớp mẫu với những cái rõ ràng nhất.

Trước khi gọi là xong dự án, dùng agent để rà soát:

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 phát hiện DELETE /api/v1/entries/{entry_id} trả mã 204 và 404 đúng (kèm tham chiếu file:line), rằng các tuyến GET dựa trên mặc định 200 hợp lệ, và xác nhận không có đầu vào người dùng nào chạm cơ sở dữ liệu ngoài ORM.

Sau khi bạn rà soát danh sách, gửi yêu cầu tiếp theo để áp dụng sửa:

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.

Bước 7: README và workflow CI

Hai bước hoàn thiện để gói dự án cho đúng. Bạn có thể giảm mức suy luận của mô hình xuống Low cho cả hai. Cấu trúc README có thể đoán trước, và CI YAML về cơ bản là mẫu sẵn, nên không có gì cần suy luận, và trả phí cho mức suy luận cao ở đây chỉ là lãng phí tín dụng.

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

Và sau đó:

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

Sau cả bảy bước, cấu trúc dự án trông như sau:

Tổng kết

Những gì ta xây ở đây là một API nhỏ, nhưng quy trình làm việc có thể mở rộng cho bất cứ thứ gì.

Đặt AGENTS.md vào vị trí trước khi agent chạm vào bất kỳ tệp nào. Hỏi kế hoạch trước khi thực thi với bất cứ việc gì không tầm thường. Chia nhỏ prompt theo giai đoạn để có các điểm kiểm tra tự nhiên thay vì một đống diff khổng lồ để rà soát cùng lúc. Dùng @filename khi bạn muốn hỏi có mục tiêu về một tệp cụ thể. Và chạy một lượt rà soát trước khi coi tác vụ là xong, vì gần như luôn bắt thêm được điều gì đó.

GPT-5.6 Sol trong Cursor vượt trội thấy rõ so với các kết hợp trước ở khả năng bám sát tác vụ trong phiên dài, bắt bất nhất giữa các tệp, và biết khi nào nên tạm dừng để hỏi ý thay vì tiếp tục làm điều phá hỏng. Nhưng mô hình chỉ là một phần của bức tranh. Ngữ cảnh bạn đưa từ đầu, các vòng xác thực bạn chạy, và lượt rà soát ở cuối—đó mới là nơi nâng chất lượng đầu ra thực sự.

Một nguyên tắc hay về mức suy luận: dùng High cho quyết định kiến trúc, phối hợp đa tệp, và gỡ lỗi điều không hiển nhiên; dùng Medium hoặc Low cho tài liệu, boilerplate, và chỉnh sửa một tệp khi bạn chỉ nhờ mô hình gõ giúp. Cân nhắc Extra High hoặc Max cho lượt rà soát code và những chỗ sai sót đắt giá hơn một lượt agent kỹ.