aws-samples · higoyal01 · Jun 30, 2026 · Jun 30, 2026 · Jun 30, 2026
diff --git a/docs/agents/lambda-runtime-upgrade.md b/docs/agents/lambda-runtime-upgrade.md
@@ -0,0 +1,147 @@
+# Lambda Runtime Upgrade Agent
+
+Discovers Lambda functions running on deprecated or end-of-life runtimes,
+analyzes their source code for compatibility issues with newer runtimes,
+and provides step-by-step migration guidance with concrete code changes.
+
+**Representative prompts:**
+- "Which of my Lambda functions are on deprecated runtimes?"
+- "Analyze my-function for upgrading from Python 3.8 to 3.12"
+- "Generate a runtime upgrade report"
+- "How do I migrate my Node.js 16 Lambda to Node.js 20?"
+
+## User Interaction Flow
+
+The agent follows a **region-selection-first** workflow:
+
+1. **Region Discovery** — Scans all enabled AWS regions in parallel to find
+   which have Lambda functions and how many are deprecated/EOL.
+2. **Region Selection** — Presents a summary table and asks the user which
+   regions to include in the report.
+3. **Multi-Region Scan** — Scans selected regions in parallel for deprecated
+   functions using `get_deprecated_functions_multi_region`.
+4. **Code Analysis** — Downloads code for the top 5 CRITICAL/HIGH priority
+   functions only (speed optimization).
+5. **Report Generation** — Produces a structured report with executive summary,
+   region inventory, code analysis, and migration playbook.
+
+**Target report generation time: 5-10 minutes** (achieved via parallel region
+scanning, selective code download, and knowledge-base-driven guidance for
+lower-priority functions).
+
+## Supported runtimes
+
+| Family | Versions tracked | Key migration concerns |
+|--------|-----------------|----------------------|
+| Python | 3.8 → 3.13 | Removed stdlib modules (3.12), boto3 bundling |
+| Node.js | 14.x → 22.x | AWS SDK v2→v3, CommonJS→ESM, OpenSSL 3.0 |
+| Java | 8 → 21 | JPMS modules, javax.* removal, SDK v1→v2 |
+| .NET | 6 → 8 | AOT compilation, System.Text.Json changes |
+| Ruby | 3.2 → 3.3 | Minimal breaking changes |
+| Custom | provided.al2 → al2023 | glibc 2.34+, OpenSSL 3.0, recompile natives |
+
+## Tools (7)
+
+| Tool | Purpose | Performance |
+|------|---------|-------------|
+| `discover_lambda_regions` | Find all regions with Lambda functions | ~15-30s (parallel scan) |
+| `list_functions_by_runtime` | List functions filtered by runtime/region | ~5-10s per region |
+| `get_function_configuration` | Detailed function config | ~1-2s per function |
+| `get_function_code` | Download source for analysis | ~3-10s per function |
+| `get_runtime_support_status` | All runtimes with dates | Instant (static data) |
+| `get_deprecated_functions` | Deprecated functions in one region | ~5-10s per region |
+| `get_deprecated_functions_multi_region` | Deprecated functions across regions (parallel) | ~15-30s total |
+
+## Deploy mode
+
+Single mode — uses the Lambda execution role (or cross-account role if
+configured) to read function metadata and code. Read-only; does NOT
+modify any functions.
+
+## Prerequisites
+
+No special setup beyond standard deployment. The agent needs:
+- `lambda:ListFunctions` — enumerate functions
+- `lambda:GetFunction` — download deployment package
+- `lambda:GetFunctionConfiguration` — read runtime/layer/handler config
+- `ec2:DescribeRegions` — discover enabled regions
+
+For cross-account scanning, configure `CROSS_ACCOUNT_ROLE_ARN` with the
+above permissions in the target account.
+
+## Speed Optimizations
+
+The agent targets 5-10 minute report generation through:
+
+1. **Parallel region discovery** — All regions scanned concurrently (10 threads)
+2. **Multi-region deprecated scan** — Single tool call scans all selected regions in parallel
+3. **Selective code analysis** — Only top 5 CRITICAL/HIGH functions get code downloaded
+4. **Knowledge-base guidance** — MEDIUM/LOW functions get migration advice from the
+   embedded runtime knowledge base without code download
+5. **Reduced report sections** — 3 sections (down from 5) with only one dependency chain
+
+## Data model
+
+### Tool: `discover_lambda_regions`
+
+```json
+{
+  "regions_with_functions": [
+    {
+      "region": "us-east-1",
+      "total_functions": 45,
+      "deprecated_count": 8,
+      "eol_count": 3,
+      "needs_attention": 11,
+      "runtimes": {"python3.8": 3, "nodejs16.x": 5, "python3.12": 37}
+    }
+  ],
+  "total_regions": 5,
+  "total_functions": 120,
+  "total_deprecated": 15,
+  "total_eol": 5,
+  "total_needing_attention": 20
+}
+```
+
+### Tool: `get_deprecated_functions_multi_region`
+
+```json
+{
+  "results_by_region": [
+    {
+      "region": "us-east-1",
+      "functions": [
+        {
+          "function_name": "my-api-handler",
+          "runtime": "python3.8",
+          "runtime_status": "end_of_life",
+          "upgrade_target": "python3.12",
+          "handler": "handler.lambda_handler",
+          "last_modified": "2024-03-15T10:30:00Z",
+          "code_size_bytes": 45000
+        }
+      ],
+      "count": 8
+    }
+  ],
+  "total_functions": 15,
+  "regions_scanned": 3,
+  "by_runtime": {
+    "python3.8": {"count": 5, "status": "end_of_life", "upgrade_target": "python3.12"},
+    "nodejs16.x": {"count": 10, "status": "deprecated", "upgrade_target": "nodejs20.x"}
+  },
+  "by_priority": {"end_of_life": 5, "deprecated": 10, "approaching": 0}
+}
+```
+
+## Known gotchas
+
+| Symptom | Likely cause | Fix |
+|---------|-------------|-----|
+| `discover_lambda_regions` slow | Many enabled regions with functions | Normal — scanning 15+ regions takes ~30s |
+| `get_function_code` returns empty files | Function uses container image packaging (`PackageType: Image`) | Container images can't be downloaded via GetFunction. Check `package_type` in config first. |
+| Code extraction hits size limit | Large deployment package with bundled deps | Use `include_patterns` param to target specific files, or increase `max_file_size_kb`. |
+| Cross-account functions not listed | Missing IAM permissions in target account | Ensure the cross-account role has `lambda:ListFunctions` + `lambda:GetFunction` + `ec2:DescribeRegions`. |
+| Runtime shows "unknown" | New runtime not yet in the support data table | Update `RUNTIME_SUPPORT_DATA` in the handler. |
+| Report takes >10 min | Too many CRITICAL/HIGH functions triggering code download | The agent limits to top 5; if you have more, run a second pass. |
diff --git a/src/agents/.hierarchy-lambda-runtime-upgrade-agent.json b/src/agents/.hierarchy-lambda-runtime-upgrade-agent.json
@@ -0,0 +1,13 @@
+{
+  "lambda-runtime-upgrade-agent": {
+    "description": "Lambda runtime upgrade assistant \u2014 discovers functions on deprecated runtimes, analyzes code compatibility, and provides migration guidance for Python, Node.js, Java, .NET, and Ruby runtime upgrades",
+    "dir": "agents/worker",
+    "model": "global.anthropic.claude-sonnet-4-6",
+    "prompt": "You are the Lambda Runtime Upgrade Agent for the CloudOps Multi-Agent Platform.\n\nYou help users upgrade their AWS Lambda function runtimes by discovering outdated functions, analyzing code for compatibility issues, and producing structured migration reports.\n\nTools available via the gateway:\n- discover_lambda_regions: Find all regions with Lambda functions (with counts + deprecated status).\n- list_functions_by_runtime: List functions filtered by runtime/region with status.\n- get_function_configuration: Get detailed function config (layers, handler, memory, env vars).\n- get_function_code: Download function source code for compatibility analysis.\n- get_runtime_support_status: All Lambda runtimes with deprecation/EOL dates.\n- get_deprecated_functions: Find deprecated/EOL functions in a SINGLE region.\n- get_deprecated_functions_multi_region: Find deprecated/EOL functions across MULTIPLE regions in parallel (fast).\n\n\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\nWORKFLOW\n\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\nSTEP 1 \u2014 DETERMINE IF REGIONS ARE SPECIFIED:\n- If the request specifies regions \u2192 skip to STEP 3 with those regions.\n- If the request says 'all regions' or 'discover all regions' \u2192 call discover_lambda_regions, then use ALL regions with needs_attention > 0. Skip to STEP 3.\n- If the request is a general question like 'which functions are deprecated?' with NO region specified \u2192 call discover_lambda_regions, show the user a region table, and ask which regions they want in the report. Wait for their answer.\n\nSTEP 2 \u2014 REGION SELECTION (only if user didn't specify):\nShow: Region | Total Functions | Deprecated | EOL | Needs Attention\nAsk: 'Which regions should I include? (all with issues / specific ones)'\n\nSTEP 3 \u2014 SCAN:\nCall get_deprecated_functions_multi_region with the selected/specified regions and include_approaching_deprecation=true.\n\nSTEP 4 \u2014 REPORT:\nFor speed (target: 5-10 min total):\n- Only call get_function_code for the top 5 CRITICAL/HIGH priority functions.\n- For MEDIUM/LOW functions, provide guidance from the knowledge base WITHOUT downloading code.\n- Skip get_function_configuration unless you need layer/handler details.\n\nSINGLE FUNCTION: If the user asks about ONE specific function, skip everything above \u2014 just call get_function_configuration + get_function_code for that function.\n\nCRITICAL: If the request contains 'Execute immediately' or 'Do NOT ask the user', NEVER ask questions \u2014 just execute all steps automatically using all regions with issues.\n\n\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\nREPORT FORMAT\n\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n## HOW TO USE THIS REPORT\n1. Review the Executive Summary for scope and urgency.\n2. Address CRITICAL priority functions first (EOL runtimes \u2014 security risk).\n3. For each function, follow its Migration Checklist.\n4. Test in non-production before deploying.\n5. Update CI/CD pipelines that pin the old runtime.\n6. Verify Lambda layers are compatible with the new runtime.\n7. Monitor CloudWatch metrics post-upgrade.\n\n## EXECUTIVE SUMMARY\n- Total functions requiring upgrade: N\n- By priority: CRITICAL: X | HIGH: Y | MEDIUM: Z\n- Regions scanned: list\n\n## REGION: {region-name}\n### Function: {function-name}\n| Field | Value |\n|-------|-------|\n| Current Runtime | ... |\n| Target Runtime | ... |\n| Priority | CRITICAL / HIGH / MEDIUM |\n| Risk Level | LOW / MEDIUM / HIGH |\n| Estimated Effort | 1-2 hours / half day / 1-2 days |\n\n**Code Changes Required:** (only for CRITICAL/HIGH with code analysis)\n**Library Upgrades:** table\n**Migration Checklist:** checkboxes\n\n\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\nPRIORITY RULES\n\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n- CRITICAL: Runtime past End-of-Life. No security patches. Upgrade immediately.\n- HIGH: Runtime deprecated. Limited support.\n- MEDIUM: Deprecation within 6 months. Plan now.\n- LOW: Active but newer LTS exists. Upgrade at convenience.\n\n\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\nRUNTIME MIGRATION KNOWLEDGE BASE\n\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\nPYTHON (3.8\u21923.12/3.13):\n- 3.11\u21923.12: REMOVED modules: distutils, imp, aifc, audioop, cgi, cgitb, chunk, crypt, imghdr, mailcap, msilib, nis, nntplib, ossaudiodev, pipes, sndhdr, spwd, sunau, telnetlib, uu, xdrlib.\n- AWS SDK: boto3/botocore bundled version changes. Pin in requirements.txt.\n\nNODE.JS (16\u219218\u219220\u219222):\n- 16\u219218: fetch() global. OpenSSL 3.0. AWS SDK v3 required (v2 no longer bundled).\n- AWS SDK MIGRATION: aws-sdk (v2) \u2192 @aws-sdk/client-* (v3, modular).\n\nJAVA (8\u219211\u219217\u219221):\n- 8\u219211: JPMS modules. REMOVED: javax.xml.bind, javax.activation, CORBA.\n- AWS SDK: v1 (com.amazonaws) \u2192 v2 (software.amazon.awssdk).\n\n.NET (6\u21928): System.Text.Json breaking changes. AOT compilation.\n\nRUBY (3.2\u21923.3): Minimal breaks.\n\nCUSTOM (provided.al2\u2192al2023): glibc 2.34+, OpenSSL 3.0. MUST recompile natives.\n\n\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\nRULES\n\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n- Keep output CONCISE \u2014 bullet points, not paragraphs.\n- Only list code changes you can VERIFY from actual source code.\n- If code cannot be downloaded (container image), provide generic guidance.\n- Do NOT fabricate issues.\n- Do NOT proactively run extra queries the user didn't ask for.\n",
+    "protocol": "http",
+    "tools": [
+      "lambda-runtime"
+    ],
+    "type": "worker"
+  }
+}