What the agent does
The agent reads how the app is assembled before it adds a route. In a Flask app like miguelgrinberg/microblog, app/__init__.py has a create_app(config_class=Config) factory that initialises Flask-SQLAlchemy, Flask-Migrate, Flask-Login, Flask-Mail, Flask-Moment and Flask-Babel, sets app.elasticsearch to a client only when ELASTICSEARCH_URL is configured and to None otherwise, creates app.redis with Redis.from_url(app.config['REDIS_URL']) and an rq queue named microblog-tasks, and registers five blueprints: errors, auth at /auth, main, cli and api at /api. config.py reads DATABASE_URL (rewriting postgres:// to postgresql://) and falls back to a SQLite app.db, defaults REDIS_URL to redis://, and leaves ELASTICSEARCH_URL unset. requirements.txt pins Flask 3.0.0, SQLAlchemy 2.0.23, redis 5.0.1, rq 1.15.1, elasticsearch 8.11.0 and gunicorn 21.2.0. There is no health route: every route under app/api requires token_auth.login_required, and main.index requires a login.
How it is deployed decides what a probe can reach. The Dockerfile copies the app onto python:slim, and boot.sh loops on flask db upgrade until it succeeds and then execs gunicorn on port 5000; the Procfile runs the same gunicorn plus rq worker microblog-tasks; under deployment/supervisor/microblog.conf gunicorn binds localhost:8000 with four workers, and deployment/nginx/microblog proxies / to it and serves /static itself. So the agent adds a health blueprint under app/health/ registered in create_app with no login requirement: GET /health/live answers 200 with {"status": "ok"} and touches nothing, so a process that has started but lost its database still counts as alive; GET /health/ready runs db.session.execute(sa.text('SELECT 1')), calls current_app.redis.ping(), and calls current_app.elasticsearch.ping() only when the client exists, reporting it as disabled otherwise, the same optionality app/search.py applies when it returns [], 0 without a client. Any failed check answers 503 with each dependency's status, built the way app/api/errors.py's error_response builds payloads, with Cache-Control: no-store.
Two details from the code shape the route. Redis.from_url does not connect, so a wrong REDIS_URL only surfaces on ping(), which is why readiness has to call it rather than trust the object exists; and main.before_request writes last_seen and commits for an authenticated user on every request, which the health routes avoid by being anonymous, so a probe every few seconds never writes a row. The agent also adds a HEALTHCHECK to the Dockerfile against port 5000 only if asked, because boot.sh already gates the container on migrations and the probe belongs to whoever runs the container.
Tests go in tests.py, the repository's only test file: a unittest suite with a TestConfig(Config) that sets TESTING, an in-memory sqlite:// database and ELASTICSEARCH_URL = None, a setUp that creates the app, pushes the context and runs db.create_all(), and unittest.main(verbosity=2) at the bottom. The agent adds a HealthCase in the same style using self.app.test_client(): /health/live answers 200; /health/ready answers 200 with redis.ping patched to return True through unittest.mock.patch.object and elasticsearch reported as disabled; and /health/ready answers 503 with ping raising redis.exceptions.ConnectionError. It runs python tests.py, since there is no pytest in requirements.txt and no CI workflow in the repository, and flask routes to show the two new routes, and quotes both in the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add health checks to this Flask app. Read app/__init__.py, config.py, app/api/errors.py, app/errors/handlers.py, app/search.py, boot.sh, the Procfile and the deployment directory first. Add a health blueprint with GET /health/live, which answers 200 with no dependencies, and GET /health/ready, which runs SELECT 1 through the SQLAlchemy session, pings Redis, and pings Elasticsearch only when the app has a client, reporting it as disabled otherwise; answer 503 with each dependency's status when any check fails, send Cache-Control: no-store, and require no login. Register the blueprint in create_app. Add a unittest case to tests.py in the existing style with the app's test client and TestConfig: live answers 200, ready answers 200 with Redis's ping patched to succeed, and ready answers 503 with ping raising a connection error. Run python tests.py and flask routes. Do not change requirements.txt, the Dockerfile or the deployment files. Open a pull request that lists the routes and what each checks and quotes the test 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
What comes back is a pull request on its own branch adding app/health/__init__.py and app/health/routes.py, one register_blueprint line in create_app, and a HealthCase in tests.py. The body lists the two routes, which dependency each checks and what ready reports for Elasticsearch when it is not configured, and quotes the python tests.py output and the flask routes table showing the new entries.
The session read names the repository and the pull request, and the transcript keeps the files opened, the first test run in which the new cases failed before the blueprint existed, the passing run, and the flask routes output. The changes route on the session lists the files with their diff.
Before merging, a reviewer checks that ready really calls ping() rather than checking the client exists, that Elasticsearch is optional only when the app's client is None and not when a configured one is down, that the routes carry no login_required and are outside the /api blueprint's token auth, and that the probe path is the one their nginx or container runtime will call.
Run it on every new Flask service
When a repository is created, a handler on your server receives GitHub's repository event and sends POST /o/{org}/sessions with this prompt and the new repository in resources. For services that already exist, a script lists what the Rush GitHub App installation can reach with GET /o/{org}/github, checks each for a health route, and starts one run per repository without one, each with its own request_id.
With a webhook_url on the key, each turn's end arrives as run.completed, run.failed or run.cancelled, signed per Standard Webhooks, and data.session_url reads back the pull request. A key may have at most max_concurrent runs in progress, 4 by default, and starting one more answers 202 with status: "queued", so a batch across many Flask services goes out in one pass and each queued run starts as an earlier one finishes.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The route is ten lines; what takes the time is reading how the app is wired, which dependencies are optional, what the deployment files expose, and writing tests that patch Redis the way the existing suite patches nothing. The agent reads all of that in its own sandbox, runs tests.py there, and keeps the output, so the pull request arrives with the evidence a repository without CI otherwise lacks.
Nothing is set up on a laptop: no Redis, no Elasticsearch, no .env. Several services get the same pair of routes at once, each in its own sandbox and pull request, and a follow-up about a dependency's status wakes the same sandbox with the code still checked out.
Frequently asked questions
Should Redis being down make the app unready when only the export job uses it?
That is a choice, and the default reports it. The queue backs export_posts in app/tasks.py and the Task.get_rq_job lookups on the profile page, so a dead Redis degrades the app without breaking logins. Say degraded in the prompt and the agent reports Redis in the body but keeps the status 200 while the database answers.
Does the ready check hit Elasticsearch when it is not configured?
No. create_app leaves app.elasticsearch as None when ELASTICSEARCH_URL is unset, and app/search.py already treats that as search switched off, so ready reports disabled and passes. A configured client that cannot answer ping() fails the check.
Which port does the probe use?
Whichever gunicorn binds: 5000 in the container from boot.sh, 8000 under the supervisor config, behind nginx on 443 if you proxy /health too. The route is the same in each; the pull request lists them so you can point the probe at the right one.
What about the rq worker?
It has no HTTP server, so these routes say nothing about it. The worker process is supervised separately in deployment/supervisor/microblog-tasks.conf and by the worker line of the Procfile; a worker health check would be a different job.