What the agent does
The agent starts by listing every runtime the CDK code names, because the retired ones hide in constructs rather than in a lockfile. In a repository like aws-samples/aws-cdk-examples a grep for Runtime.PYTHON_ and Runtime.NODEJS_ across the python/ and typescript/ trees shows the split at once: the TypeScript examples are on NODEJS_24_X or NODEJS_LATEST (typescript/postgres-lambda/lib/postgres-lambda-stack.ts, typescript/lambda-layer/lib/lambda-layer-stack.ts), while the Python examples still carry PYTHON_3_7 in python/url-shortener/app.py and python/lambda-s3-trigger/s3trigger/s3trigger_stack.py, five times in python/image-content-search/stack/cdk.py, and PYTHON_3_8 on all three functions in python/api-eventbridge-lambda/api_eventbridge_lambda/api_eventbridge_lambda.py. python/lambda-layer/app.py is the awkward one: its LayerVersion lists compatible_runtimes of PYTHON_3_6, PYTHON_3_7 and PYTHON_3_8, and the function that uses the layer is on PYTHON_3_8, so the layer and the function have to move together or the synth fails.
Next it checks what each handler actually imports, since a runtime bump is only safe if the code runs on the new interpreter. python/url-shortener/lambda/handler.py uses json, os, uuid, logging and boto3, all present in every current Python runtime; python/lambda-layer/lambda/index.py does import common from the layer's layer/python/common.py, which is plain Python. Each example's requirements.txt pins aws-cdk-lib>=2.262.0,<3.0.0 and constructs>=10.5.0,<11.0.0, so the Runtime members for current Python versions already exist in the installed library and no CDK upgrade is needed to name them. The agent picks the newest runtime the installed aws-cdk-lib exposes rather than a version it remembers, and for a layer it sets compatible_runtimes to the same list the functions use.
Then it proves each change the way the repository's own CI does. .github/workflows/build-pull-request.yml builds only the example directories a pull request touched, per language, with .github/actions/setup-language installing Python 3.12 for the python matrix row. The agent repeats that locally: a virtual environment per example, pip install -r requirements.txt, then cdk synth with no AWS credentials, which resolves the construct tree and writes the CloudFormation template to cdk.out. A diff of the template before and after the edit should show only the Runtime property of each AWS::Lambda::Function and the CompatibleRuntimes of each AWS::Lambda::LayerVersion; anything else in the diff is a sign the change did more than it should.
Examples the agent cannot synthesize are reported, not guessed at. python/url-shortener/app.py imports waltersco_common and maps a custom subdomain, so it needs the account context in cdk.context.json; the agent still edits its runtime line and says in the pull request which examples it proved with a synth and which it changed on the strength of the handler read alone.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Find every Lambda function and layer in this CDK repository whose runtime is a retired Python or Node.js version, and move each to the newest runtime the installed aws-cdk-lib exposes. Move a layer's compatible_runtimes together with the functions that use it. Read each handler to confirm it imports nothing the new runtime drops. For each changed example, install its requirements and run cdk synth, then diff the CloudFormation template against the one from before the change and confirm only runtime properties moved. Open a pull request listing each file, the runtime before and after, and which examples synthesized; say plainly which ones you could not synthesize and why.",
"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 touches only the stack files that named a retired runtime: in this repository app.py or the stack module under each affected python/ example, with the LayerVersion in python/lambda-layer/app.py changed in the same commit as its function. Its description is a table of file, construct id, old runtime and new runtime, followed by the cdk synth result for each example and the template diff lines, which should name only Runtime and CompatibleRuntimes. The examples that could not be synthesized are in their own section with the error, such as a missing account context, so nobody mistakes an edited file for a proven one.
A reviewer opens one of the diffs in cdk.out, checks that no IAM statement, environment variable or asset hash moved along with the runtime, and reads the handler for anything version-specific the agent might have missed, such as a dependency vendored for an older interpreter. The full pip install and cdk synth output for every example is in the session transcript at GET /o/{org}/sessions/{id}/messages, and the pull request itself runs the repository's own build-pull-request.yml on the changed directories.
Nothing is deployed. cdk synth writes templates and assets to cdk.out inside the sandbox and makes no AWS call, so the pull request is the whole output and the account is untouched until someone merges and deploys it.
Run it on every runtime deprecation announcement
AWS publishes dates when a Lambda runtime stops receiving updates and when functions on it can no longer be created or updated. When one of those announcements lands, or on a weekly schedule your own scheduler runs, send POST /o/{org}/sessions with this body once per repository that defines Lambda functions in CDK, with a request_id that is a UUID v5 of the announcement and the repository so a retried send returns the same run. Each run reads the runtimes the installed aws-cdk-lib exposes at that moment, so the target is never stale.
A webhook URL on the API key gets run.completed with the session URL when each run ends. With several CDK repositories the sends go out together; a key runs at most max_concurrent sessions at once, 4 by default, and the rest answer 202 with status queued and start as slots free.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
Finding retired runtimes is a grep; proving each bump is the slow part, because every example needs its own virtual environment, its own pip install and a cdk synth that takes long enough to make a laptop loop tedious across dozens of directories. In Rush each run has its own sandbox with Node, Python and the CDK CLI, the installs and synths happen there, and the template diffs land in the transcript where a reviewer can read them.
A pull request that pairs each runtime line with its synth result and template diff is easier to merge than one that only edits strings, and it is honest about the examples it could not prove. Several repositories can be upgraded at once, one run each, and none of them needs AWS credentials to get as far as a synthesized template.
Frequently asked questions
Does it need AWS credentials?
No. cdk synth resolves constructs and writes CloudFormation templates without calling AWS. The only credentials-shaped thing an example may need is a cdk.context.json with account values, and an example that lacks one is reported as not synthesized rather than invented.
Which runtime does it pick?
The newest member of aws_lambda.Runtime for that language that the installed aws-cdk-lib exposes, read from the library in the sandbox, not from memory. If you want a specific version, name it in the prompt and the agent uses that instead.
What about the layer in lambda-layer?
A LayerVersion whose compatible_runtimes omit the function's new runtime fails at synth, so the agent changes the layer list and the function runtime in the same commit and checks the template shows both. The common module in the layer is plain Python and needs no change.
Will it also bump aws-cdk-lib?
Only if the current library has no member for a current runtime, which is not the case here: requirements.txt already allows aws-cdk-lib>=2.262.0. Ask for a library bump explicitly if you want one, and the agent runs the same synth check after it.
My handlers depend on packages compiled for the old interpreter. Will it notice?
It reads each handler's imports and any requirements.txt the function code ships with. A compiled dependency pinned to an old interpreter is flagged in the pull request as needing a rebuild, and that function's runtime is left for you to decide rather than changed blindly.
More AWS CDK jobs
The same job on other stacks
- Upgrade the Lambda Runtime in a Serverless Service (Serverless Framework)