What the agent does
The agent reads where the supported versions are declared, because there are always several places. In a library shaped like encode/httpx, .github/workflows/test-suite.yml runs a matrix of 3.9, 3.10, 3.11, 3.12 and 3.13 with allow-prereleases: true on actions/setup-python, pyproject.toml lists the same five as Programming Language :: Python :: 3.x classifiers under requires-python = ">=3.9", README.md and docs/index.md say the library requires Python 3.9 or newer, and CHANGELOG.md's [UNRELEASED] section already records dropping 3.8 and earlier entries read Add support for Python 3.12. (#2854). The highest version in the matrix is the one to move past.
It then makes the new interpreter available and runs everything the CI runs. scripts/install creates a venv and installs requirements.txt, which pins the tooling, coverage, mypy, pytest, ruff, trio, uvicorn and trustme, and installs the package with every extra, brotli, cli, http2, socks and zstd. Under the new interpreter the agent runs scripts/check, which is ruff format --diff, mypy and ruff check, then scripts/build, which builds the wheel and the mkdocs site, then scripts/test and scripts/coverage, which fails under one hundred percent. The pytest configuration sets filterwarnings = error, so a new DeprecationWarning from the standard library on the new release surfaces as a failure rather than a note, which is exactly the signal this job exists to find.
What breaks is fixed at the source, and what cannot be fixed yet is pinned down. A deprecation in the standard library gets the replacement call, guarded with a sys.version_info check only when older interpreters need the old one, in the style of the single existing check in tests/client/test_auth.py. A failure inside a pinned tool is handled by raising that tool's pin in requirements.txt to the first release that supports the interpreter, with the changelog entry of that tool linked in the pull request. An extra whose compiled dependency has no wheel yet for the new release is left in the matrix with a note, not removed, because dropping an extra silently is worse than a known gap.
The declarations are then updated together: the new version appended to the workflow matrix, a new classifier line in pyproject.toml, a Support for Python 3.x line under ### Added in the [UNRELEASED] changelog section in the repository's own phrasing, and no change to requires-python, because adding a version at the top does not move the floor. The agent runs the suite once more on the lowest version in the matrix too, so a fix for the new release is shown not to break the oldest.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add the newest released Python version to this library's supported versions. Read .github/workflows/test-suite.yml, pyproject.toml, requirements.txt, scripts/install, scripts/check, scripts/build, scripts/test, scripts/coverage, CHANGELOG.md, README.md and docs/index.md first, and find the highest version the matrix lists. Install the next minor release of CPython after it, create the venv with scripts/install -p pointing at that interpreter, and run scripts/check, scripts/build, scripts/test and scripts/coverage under it. Fix any failure at its source: replace deprecated standard library calls with a version guard only where older interpreters need the old call, raise a pinned tool in requirements.txt to its first release that supports the interpreter and link that tool's changelog, and if a compiled extra has no wheel yet, keep the version in the matrix and say so rather than removing the extra. Append the version to the workflow matrix, add its classifier in pyproject.toml, add a changelog line under Added in the UNRELEASED section in the file's existing phrasing, and leave requires-python unchanged. Run the suite again on the lowest version in the matrix. Open a pull request that quotes the test and coverage output on both interpreters and lists each fix with its cause.",
"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
What comes back is a pull request on its own branch that adds one entry to the matrix in .github/workflows/test-suite.yml, one classifier line in pyproject.toml and one line in CHANGELOG.md, plus whatever the new interpreter made necessary: a guarded replacement for a deprecated call, a raised tool pin in requirements.txt, or nothing at all when the suite was already clean. requires-python, README.md and docs/index.md are unchanged, because the floor did not move.
The description quotes the scripts/test and scripts/coverage output under the new interpreter and under the lowest one in the matrix, and the scripts/check result, so a reviewer sees that mypy and ruff pass on both. Each code change has a sentence naming the deprecation or the tool release that caused it, with a link to the upstream note, and the description says in one line whether any extra lacks a wheel on the new release.
Before merging, a reviewer watches the workflow run on the pull request, which now has one more job, checks the changelog line against the project's phrasing, and decides whether the publish workflow, which pins a single Python version for building, should move as well. A follow-up on the same session can make that change.
Run it on every Python release
This is an annual job that is easiest the week the release lands: a POST /o/{org}/sessions with this prompt and the repository in resources, sent from the terminal when the release announcement arrives, and the branch is ready while the team keeps working. The sandbox parks with its disk when the turn ends, so a follow-up such as also run the suite with the free-threaded build and report what differs wakes it with both interpreters and the venv still there.
With a webhook URL on the API key, Rush posts run.completed or run.failed with the session_url when the turn ends. A maintainer with several libraries sends the same prompt to each repository, one run per repository, and each run reads that library's own matrix, pins and changelog.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Testing on a new interpreter means installing it, rebuilding a venv with every extra, and running a suite that treats warnings as errors, then doing it again on the oldest version to be sure the fix holds. The agent does both in its own sandbox and keeps every command and its output in the run's record, so the laptop never needs a second Python.
The record is also where the causes are. The transcript shows the warning that became a failure, the standard library note it points to, the tool release that fixed a pinned dependency, and the coverage report at one hundred percent on both interpreters. A reviewer who prefers to wait for a wheel can say so in a follow-up and the parked sandbox adjusts the matrix with the fixes kept.
Frequently asked questions
Which Python version does it add?
The next minor release after the highest one the workflow matrix lists, read from the file rather than assumed, so the same prompt works next year. The pull request names the version and links the release notes it checked for deprecations.
Does it drop the oldest version?
No. Adding a version at the top does not change requires-python or the lowest matrix entry, and dropping a version is a separate decision with a changelog entry of its own. The agent runs the suite on the lowest version to prove its fixes do not break it.
What if a dependency has no wheel yet for the new release?
The version stays in the matrix and the pull request says which extra lacks a wheel and where to watch for it, rather than removing the extra or marking the job as allowed to fail. A follow-up can re-run the suite once the wheel is published.
Why do warnings matter here?
Because the pytest configuration sets filterwarnings to error, so any DeprecationWarning the new interpreter raises fails the suite. That is the mechanism that makes an interpreter upgrade visible, and the agent fixes each warning at its source instead of adding an ignore.
Will it change the publish workflow?
Not in this pull request. publish.yml builds the release on a single pinned Python, and moving it is a release decision the description raises for the maintainer. A follow-up on the same session can make the change.
More Python jobs
More jobs like this: Hand off a long task
- Set Least-Privilege Permissions on GitHub Actions Workflows (GitHub Actions)
- Add Lighthouse CI to a Docusaurus Site (Docusaurus)
- Add Lighthouse CI to an Eleventy Site (Eleventy)