eks-to-agentcore

EKS to AgentCore Migration Guide

Overview

Migrate AI agents from Amazon EKS (containerized Kubernetes workloads) to Amazon Bedrock AgentCore (serverless, purpose-built agent runtime). This skill provides the domain knowledge to guide the migration end-to-end, from assessment through cutover.

AgentCore eliminates Kubernetes infrastructure management by providing a fully managed runtime with built-in session isolation (microVMs), memory, identity, observability, and consumption-based pricing.

---

Process

Phase 1: Assess

1. Identify agent workloads on EKS — use scan_eks_cluster MCP tool or kubectl get deployments
2. For each agent, evaluate:
   • Python version (must be 3.10+)
   • Framework (Strands, LangChain, LangGraph, CrewAI, Google ADK, OpenAI Agents, or custom)
   • External dependencies (databases, APIs, caches)
   • Kubernetes-specific dependencies (PVCs, Secrets, ConfigMaps, HPA, service mesh)
   • Entrypoint file (AgentCore expects main.py)
3. Use assess_agent or assess_cluster MCP tools for automated assessment
4. Prioritize: start with low-complexity agents (supported framework, no PVCs, no custom networking)

Phase 2: Scaffold

1. Install AgentCore CLI: npm install -g @aws/agentcore
2. Create project: agentcore create --name <AgentName> --defaults
3. Use generate_agentcore_project MCP tool for customized scaffold commands
4. Choose build type:
   • CodeZip (default, recommended) — no Dockerfile needed
   • Container — only if agent has heavy system-level dependencies (CUDA, custom native libs)

Phase 3: Migrate Code

1. Copy agent source to app/<AgentName>/
2. Create main.py with AgentCore Runtime wrapper — use generate_main_py MCP tool
3. The wrapper pattern for Strands agents:

   from strands import Agent
   from bedrock_agentcore.runtime import BedrockAgentCoreApp
   
   agent = Agent(model="...", system_prompt="...", tools=[...])
   app = BedrockAgentCoreApp()
   
   @app.entrypoint
   def invoke(payload):
       response = agent(payload.get("prompt", ""))
       return response.message["content"][0]["text"]
   
   if __name__ == "__main__":
       app.run()
   

4. Update pyproject.toml — remove K8s-specific deps (gunicorn, uvicorn, kubernetes client)
5. Remove web framework serving code (Flask/FastAPI) — AgentCore handles HTTP natively

Phase 4: Migrate Configuration

1. Secrets → agentcore add credential --name <svc> --api-key <key> or --type oauth
2. ConfigMaps/env vars → agentcore.json configuration
3. Networking:
   • Internet-only APIs → "networkMode": "PUBLIC" (default)
   • Private resources (RDS, ElastiCache) → "networkMode": "VPC"
4. Memory/state (Redis, DynamoDB) → agentcore add memory --strategies SEMANTIC,SUMMARIZATION
5. IRSA → AgentCore Identity (CDK creates execution roles automatically)

Phase 5: Test & Deploy

1. Test locally: agentcore dev then agentcore dev "test prompt"
2. Preview: agentcore deploy --plan
3. Deploy: agentcore deploy
4. Verify: agentcore status and agentcore invoke --runtime <AgentName> "test"
5. Set up CI/CD — use generate_cicd_pipeline MCP tool

Phase 6: Cutover

1. Run both EKS and AgentCore agents in parallel
2. Route traffic gradually using weighted routing
3. Monitor via agentcore logs and agentcore traces list
4. After validation, scale down EKS: kubectl scale deployment <name> --replicas=0
5. Clean up K8s resources (Deployment, Service, Ingress, HPA, Secrets, ConfigMaps)

---

Key Decisions

Decision	Recommendation
Build type	CodeZip unless you need CUDA/GPU or custom native libraries
Network mode	PUBLIC for internet APIs, VPC for private resources (RDS, ElastiCache)
Framework	Strands has the smoothest migration path; LangChain/LangGraph supported; custom needs service contract
Memory	Use AgentCore Memory to replace Redis/DynamoDB session state
CI/CD	agentcore deploy replaces Docker build + ECR push + kubectl apply

---

Common Pitfalls

• AgentCore Memory is NOT available during local dev (agentcore dev). Deploy first to test memory.
• Entrypoint must be main.py (or configured in agentcore.json)
• Remove Flask/FastAPI/uvicorn — AgentCore Runtime handles HTTP serving
• Extended execution supports up to 8 hours. Decompose longer workloads.
• First deployment takes a few minutes while CDK bootstraps your account
• EKS tokens expire every ~15 minutes. Refresh with aws eks update-kubeconfig

---

MCP Tools Reference

This skill works with the eks-to-agentcore MCP server. Available tools:

Tool	Purpose
scan_eks_cluster	Discover AI agent deployments on EKS (specify namespace for least privilege)
assess_agent	Assess a single agent for migration compatibility
assess_cluster	Full cluster scan + assessment report
generate_agentcore_project	Generate agentcore CLI scaffold commands
generate_cicd_pipeline	Generate CodeBuild or GitHub Actions pipeline config
generate_main_py	Generate ready-to-use main.py with AgentCore Runtime wrapper
get_eks_agentcore_feature_map	EKS-to-AgentCore feature mapping and cleanup checklist

---

Guidelines

• Always specify a namespace when scanning (scan_eks_cluster(namespace="agents")) to follow least-privilege principles
• Env var values are never captured — only names are used for heuristic analysis
• Start with the simplest agent (low complexity) as a pilot migration
• Use CodeZip build type unless you have a specific reason for Container
• Keep the EKS agent running in standby for 1-2 weeks after cutover as a rollback option
• Use agentcore deploy --plan before every deployment to preview changes