What the agent does
The agent starts from the view that lists everything. In an app like the polls demo in aio-libs/aiohttp-demos, aiohttpdemo_polls/views.py has index, which opens a session from request.app[db_key], runs select(db.Question) with no order and no limit, and hands questions.all() to templates/index.html, where a Jinja loop renders one link per question through url('poll', question_id=question.id). db.py declares Question with an integer primary key, question_text as String(200) and pub_date as a date, on SQLAlchemy 2.0.54 with asyncpg 0.32.0 per requirements-dev.txt. routes.py registers / without a name, so there is no reverse route for the index yet.
The cursor is a keyset over (pub_date, id), ordered newest first, because pub_date alone is not unique and an offset would skip or repeat rows when a poll is added between pages. The agent adds after and limit query parameters to index: limit defaults to 20 and is capped at 100, and after is a urlsafe base64 string of the last row's pub_date and id, decoded in a helper that raises web.HTTPBadRequest on anything it cannot parse, matching the error the vote view already raises for a bad choice. The query becomes select(Question).where(tuple_(Question.pub_date, Question.id) < (date, id)).order_by(Question.pub_date.desc(), Question.id.desc()).limit(limit + 1), and the extra row, when present, becomes next_cursor. The template gets an Older polls link built with url('index'), so the agent names the route in routes.py.
Tests follow the existing suite. tests/conftest.py builds the app from init_app with config/polls_test.yaml and the tables_and_data fixture loads init_db.sample_data, which inserts one question, so the new tests/test_pagination.py inserts a few dozen more through the app's session maker inside the test, with dates that tie on purpose. It asserts that the first page holds limit rows, that following the link until it disappears visits every id exactly once, that a cursor from the middle of a tie returns the right neighbour, and that ?after=garbage answers 400. pytest.ini runs with asyncio_mode = auto and turns every warning into an error, so the test uses no deprecated session API.
The check is the repository's own: make test in the demo runs pytest tests against the Postgres the db fixture creates, and the root Makefile runs pytest demos/polls with the other demos, which is what .github/workflows/ci.yml executes with a Postgres service. The agent runs flake8 from requirements-dev.txt too, since the root make lint covers the demos.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add cursor pagination to the polls index in this aiohttp app. Read aiohttpdemo_polls/views.py, routes.py, db.py, templates/index.html, tests/conftest.py, tests/test_integration.py, init_db.py, pytest.ini and requirements-dev.txt first. Replace the unbounded select in the index view with a keyset query over (pub_date, id), newest first, taking after and limit query parameters: limit defaults to 20 and is capped at 100; after is a urlsafe base64 cursor of the last row's pub_date and id, and a cursor that does not parse answers 400 with web.HTTPBadRequest. Fetch limit + 1 rows and expose next_cursor to the template as an Older polls link; name the index route so url('index') works. Add tests/test_pagination.py that inserts questions with tied dates through the app's session maker, walks every page and asserts each id appears once, checks a cursor inside a tie, and checks the 400. Run make test and flake8, and open a pull request with the output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request changes aiohttpdemo_polls/views.py, routes.py and templates/index.html, adds a small cursor module beside them and tests/test_pagination.py. Its description pastes the pytest run with the --durations=10 table that pytest.ini turns on and the flake8 result, and shows a decoded example cursor so a reviewer can see it carries a date and an integer and nothing else.
The index now answers in constant time whatever the table size, and a poll inserted while a reader is on page three does not shift what page four shows. A client that stores the cursor can resume later; a client that sends a stale cursor for a deleted row still gets the rows after it, because the comparison is on values, not on the row's existence.
Before merging, a reviewer decides the default and maximum page sizes, checks whether the (pub_date, id) index Postgres needs for the keyset should land as a migration in the same pull request or a separate one, and confirms the Older polls link text matches the site's tone.
Run it on every list view with no limit
A team with several aiohttp services starts one run per repository from the terminal: one POST /o/{org}/sessions each, with that repository in resources and a request_id that is a UUID v5 of its full name, so a retried call returns the run already started. Each run reads its own views: a service whose list is already ordered by a unique column gets a single-column cursor, one that returns JSON gets next_cursor in the body instead of a template link, and one on aiopg instead of SQLAlchemy gets the same keyset written as SQL.
Each run opens its own pull request on its own branch, and GET /o/{org}/sessions lists them newest first, so the person who started the batch reads every test result from one place.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Pagination that looks right on ten rows breaks on ten thousand, and the breakage is a missing row nobody notices. The agent proves the keyset with data it inserts itself, including the ties that make (pub_date, id) necessary, against a real Postgres in its own sandbox, and the walk-every-page test stays in the suite to catch a later change to the ordering.
The run keeps every command and its output, so the reviewer sees the test run and the lint pass without creating the database locally. Several services can be paginated at once, each in its own sandbox, and one whose view already bounds its query is left with a note instead of a second cursor.
Frequently asked questions
Why not offset and limit?
An offset counts rows from the start every time, so page cost grows with the page number, and a row inserted or deleted before the offset shifts every later page. A keyset compares against the last row's values, so each page is one indexed range scan and a concurrent insert changes nothing a reader has already seen.
Is the cursor safe to expose?
It is base64 of a date and an integer, readable by anyone, and it is treated as untrusted input: it is parsed strictly, a bad one answers 400, and the values only ever reach the query as bound parameters through SQLAlchemy. If the agent finds the team wants cursors to be opaque, it notes that signing them is a separate change.
Does the template still work with few polls?
Yes. With fewer than limit + 1 rows there is no next_cursor and the link is not rendered, so a site with three polls looks exactly as it does today. The empty state, No polls are available., is unchanged.
Does it need a database migration?
The query works without one; Postgres can scan the table. For the keyset to be fast at scale, a composite index on (pub_date, id) helps, and the agent proposes it in the pull request description rather than adding Alembic to a project that does not use it.