What the agent does
A health route in Litestar is a handler and a registration, but the project's tooling decides how it has to be written, so the agent reads that tooling first. In an app laid out like litestar-org/litestar-hello-world, app.py defines two handlers with @get: async_hello_world on /async, which awaits asyncio.sleep(0.1), and sync_hello_world on /sync with sync_to_thread=False, so Litestar runs the plain function on the event loop instead of a worker thread. Both return Dict[str, Any] with a # noqa: UP006 because pyproject.toml sets target-version = "py38" for Ruff while selecting every rule with select = ["ALL"], and the module declares __all__ = ("async_hello_world", "sync_hello_world"). app = Litestar(route_handlers=[sync_hello_world, async_hello_world]) is the whole application. pyproject.toml depends on litestar[standard]>=2.4.1, resolved to 2.4.1 in pdm.lock, supports Python 3.8 through 3.12 and runs mypy in strict mode. tests/test_app.py has two tests that open TestClient(app=app) and assert the JSON of each route.
The checks that run on a pull request are in .pre-commit-config.yaml and .github/workflows/ci.yaml. The hooks include ruff with --fix and ruff-format, codespell, mypy with litestar[standard] as an additional dependency, slotscheck, and ensure-dunder-all from flake8-dunder-all with --use-tuple, which fails if a public name is missing from __all__. The workflow runs those hooks on Python 3.11, then the test.yaml reusable workflow on 3.8 through 3.11 with coverage on 3.11, and on macOS and Windows for pushes. pdm.lock is checked by a pdm-lock-check hook, so a dependency change without a lock update fails too. None of this is visible from app.py, and a handler written without the noqa, the tuple entry or the right annotation style fails before a test runs.
The agent adds health to app.py: @get("/health", sync_to_thread=False, include_in_schema=False) on a plain function returning Dict[str, str] with {"status": "ok"}, since a health probe should not take a thread from the pool or appear in the /schema documentation Litestar generates by default. The response carries Cache-Control: no-store through the handler's response_headers so a proxy never answers a probe from cache. The name joins the __all__ tuple and the handler joins route_handlers. For an app with a database or a cache, the same handler would call each dependency and answer 503 with the failing name through a Response with status_code; this app has neither, and the pull request says where that check goes when one arrives. A second route is not added for readiness; a single /health matches what the app can report.
Then the agent runs what CI runs. It installs PDM, runs pdm install to get the locked litestar and the lint and test groups, and pdm run lint, which is pre-commit run --all-files, so Ruff, mypy, codespell and the __all__ hook all pass on the new code. It adds test_health to tests/test_app.py beside test_sync and test_async, asserting the status, the JSON and the Cache-Control header through TestClient, and a second test that reads /schema/openapi.json and asserts /health is not among its paths. It runs pdm run test and pytest tests --cov as the Makefile's coverage target does, and starts the app once with litestar run from the [standard] extra's CLI to request /health with curl as the README does for /sync and /async.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a health check endpoint to this Litestar app. Read app.py, tests/test_app.py, pyproject.toml, pdm.lock, .pre-commit-config.yaml, .github/workflows/ci.yaml, .github/workflows/test.yaml, the Makefile and README.md first. Add a GET /health handler in app.py with sync_to_thread=False and include_in_schema=False that returns {\"status\": \"ok\"} with a Cache-Control: no-store response header, annotated in the same Dict style as the existing handlers with the noqa the Ruff target needs, added to __all__ and to route_handlers. Add tests in tests/test_app.py for the status, body and header, and one that checks /health is absent from /schema/openapi.json. Install PDM, run pdm install, pdm run lint, pdm run test and pytest tests --cov, start the app with litestar run and request /health with curl, and open a pull request that shows the response and the lint and test output. Do not change pyproject.toml or pdm.lock.",
"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 app.py and tests/test_app.py and nothing else. Its description shows the curl response with its headers, the pre-commit run --all-files output with every hook passing, and the pytest summary with the new tests, and explains why the route skips the thread pool and the OpenAPI schema.
The Tests and Linting workflow runs on the pull request: the validate job runs the same hooks on 3.11, and the test job runs the suite on 3.8 through 3.11, so the Dict annotation and the noqa are checked on the oldest version the project supports. The run's record keeps the sandbox output for comparison with those checks.
Before merging, a reviewer decides whether /health should also answer HEAD for a load balancer that probes that way, whether to keep it out of the schema or document it, and where a dependency check goes once the app has a database. pyproject.toml, pdm.lock and the two existing routes are unchanged.
Run it on every Litestar service without a health route
An organisation with several Litestar services starts one run per repository from its own server: one POST /o/{org}/sessions each, with the repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own app, so a service built on the Litestar fullstack template with a database plugin gets a handler that pings the engine, and one with a Router prefix gets the route registered under it.
A team that files platform work as Linear issues runs this prompt from an automation in the Project with a linear trigger on issues labelled platform. The trigger adds the issue after the prompt, so an issue that names the probe path a Kubernetes manifest expects, or asks for separate liveness and readiness routes, reaches the agent with those names, and the pull request links back to it.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The handler is four lines, and every one of them is checked by a tool that does not run from the editor: Ruff with every rule on, mypy strict, a hook that fails when __all__ is missing a name, and a test matrix down to Python 3.8 where dict[str, str] in an annotation is a syntax the project avoids. The agent runs the same hooks and the same suite in its own sandbox through PDM, so the pull request arrives green rather than with a lint failure to fix first.
Every command stays with the run, from pdm install to the curl against litestar run, so a reviewer sees the response before merging. The same prompt runs across every Litestar service at once, each in its own sandbox and with its own pull request.
Frequently asked questions
Why sync_to_thread=False on the health handler?
A plain def handler runs in a worker thread by default so it cannot block the loop, and Litestar warns when the setting is left implicit. A health probe does no I/O and returns a constant, so running it on the loop like sync_hello_world avoids a thread hop for something a load balancer calls every few seconds.
Why keep it out of the OpenAPI schema?
Litestar serves generated documentation at /schema for every route unless include_in_schema=False. A probe is for infrastructure, not for API clients, so leaving it out keeps the documentation about the service's actual surface. A team that wants it listed removes one argument.
What does a health check look like once the app has a database?
The same handler becomes async, awaits a cheap query through the app's engine or a ping on the cache, and returns a Response with status 503 and the failing dependency's name when one raises. The pull request names that spot so the next change goes in the right place.
Will the test matrix accept the new code on Python 3.8?
Yes, as long as the annotation uses Dict from typing with the noqa: UP006 the existing handlers carry, which is why the agent copies their style instead of writing dict[str, str]. The test job runs on 3.8 first, so a slip shows in CI as well as in the sandbox.