docs(readme): Enhance local development documentation and script (windows only)

benlec · benlec · commit beca45f95327 · 2025-11-06T15:41:51.000+01:00
- Update README.md with more detailed local development workflow
- Add comprehensive explanation of how local agent development works
- Improve section on development workflow and agent restart process
- Update project structure description with more precise formatting
- Enhance `dev-local.ps1` script with robust AWS credential and environment checks
- Add detailed error handling and guidance for AWS CLI configuration
- Include version compatibility checks for AWS CLI
- Provide more informative console output during local development setup
Rationale: Improve developer onboarding experience and provide clearer guidance for local development environment setup
diff --git a/README.md b/README.md
@@ -108,12 +108,24 @@ This will:
 5. Configure the frontend to call the local agent (no authentication required)
 
 **Local Development Features:**
-- ✅ Hot reload for both frontend and agent changes
+- ✅ Frontend hot reload (Vite dev server)
+- ✅ Fast agent restart cycle (no deployment needed)
 - ✅ Authentication with Cognito is bypassed
 - ✅ Same agent code as production
-- ✅ Fast iteration cycle
+- ✅ Rapid iteration without AWS deployment
 
-**Note:** Local development uses the same `strands_agent.py` file as production. Changes made locally will be reflected when you deploy.
+**How Local Development Works:**
+- `python strands_agent.py` starts your agent as a regular Python process
+- `app.run()` in `strands_agent.py` creates HTTP server on `localhost:8080` (via `bedrock-agentcore` library)
+- Frontend sends POST requests to `/api/invocations`
+- Agent executes directly in Python, calls AWS Bedrock APIs
+- No Docker, no containers needed - just Python + web server
+
+**Development Workflow:**
+- **Frontend changes** (`frontend/` files): Hot reload automatically via Vite
+- **Agent changes** (`agent/` files): Restart required - Ctrl+C then re-run script
+
+**Note:** Agent restart takes ~10 seconds vs ~10 minutes for production deployment.
 
 ## Stack Architecture
 
@@ -128,13 +140,13 @@ This will:
 
 ```
 project-root/
-├── agent/                      # Agent runtime code
+├── agent/                     # Agent runtime code
 │   ├── strands_agent.py       # Agent implementation (Strands framework)
 │   ├── requirements.txt       # Python dependencies
 │   ├── Dockerfile             # ARM64 container definition
 │   └── .dockerignore          # Docker ignore patterns
 │
-├── cdk/                        # Infrastructure as Code
+├── cdk/                       # Infrastructure as Code
 │   ├── bin/
 │   │   └── app.ts             # CDK app entry point
 │   ├── lib/
@@ -146,7 +158,7 @@ project-root/
 │   └── package.json           # CDK dependencies
 │
 
-├── frontend/                   # React app (Vite)
+├── frontend/                  # React app (Vite)
 │   ├── src/
 │   │   ├── App.tsx            # Main UI component with auth
 │   │   ├── AuthModal.tsx      # Login/signup modal
@@ -162,6 +174,8 @@ project-root/
 │
 ├── deploy-all.ps1             # Main deployment orchestration (Windows)
 ├── deploy-all.sh              # Main deployment orchestration (macOS/Linux)
+├── dev-local.ps1              # Local development mode (Windows)
+├── dev-local.sh               # Local development mode (macOS/Linux)
 └── README.md                  # This file
 ```
 
diff --git a/dev-local.ps1 b/dev-local.ps1
@@ -1,43 +1,146 @@
 # Local Development Script - Start frontend and AgentCore backend locally
 
-Write-Host "🚀 Starting Local Development Mode" -ForegroundColor Cyan
-Write-Host "==================================" -ForegroundColor Cyan
+Write-Host "=== Local Development Mode ===" -ForegroundColor Cyan
 
-# Check if Python is available
+# Step 1: Verify AWS credentials
+Write-Host "`n[1/7] Verifying AWS credentials..." -ForegroundColor Yellow
+Write-Host "      (Required for AWS service access when running agent locally)" -ForegroundColor Gray
+
+# Check if AWS credentials are configured
+$callerIdentity = aws sts get-caller-identity 2>&1
+
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "      ❌ AWS credentials are not configured or have expired" -ForegroundColor Red
+    Write-Host "`nPlease configure AWS credentials using one of these methods:" -ForegroundColor Yellow
+    Write-Host "  1. Run: aws configure" -ForegroundColor Cyan
+    Write-Host "  2. Set environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY" -ForegroundColor Cyan
+    Write-Host "  3. Use AWS SSO: aws sso login --profile <profile-name>" -ForegroundColor Cyan
+    Write-Host "`nFor more info: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html" -ForegroundColor Gray
+    exit 1
+}
+
+# Display current AWS identity
+$accountId = ($callerIdentity | ConvertFrom-Json).Account
+$arn = ($callerIdentity | ConvertFrom-Json).Arn
+Write-Host "      ✓ Authenticated as: $arn" -ForegroundColor Green
+Write-Host "      AWS Account: $accountId" -ForegroundColor Green
+
+# Step 2: Check AWS CLI version
+Write-Host "`n[2/7] Checking AWS CLI version..." -ForegroundColor Yellow
+Write-Host "      (Ensuring compatibility with Bedrock service)" -ForegroundColor Gray
+$awsVersion = aws --version 2>&1
+$versionMatch = $awsVersion -match 'aws-cli/(\d+)\.(\d+)\.(\d+)'
+if ($versionMatch) {
+    $major = [int]$Matches[1]
+    $minor = [int]$Matches[2]
+    $patch = [int]$Matches[3]
+    Write-Host "      Current version: aws-cli/$major.$minor.$patch" -ForegroundColor Gray
+    
+    # Check if version is >= 2.31.13 (recommended for Bedrock)
+    $isVersionValid = ($major -gt 2) -or 
+                      ($major -eq 2 -and $minor -gt 31) -or 
+                      ($major -eq 2 -and $minor -eq 31 -and $patch -ge 13)
+    
+    if (-not $isVersionValid) {
+        Write-Host "      ⚠ AWS CLI version 2.31.13 or later is recommended for Bedrock" -ForegroundColor Yellow
+        Write-Host "      Your current version: aws-cli/$major.$minor.$patch" -ForegroundColor Yellow
+        Write-Host "      Consider upgrading: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html" -ForegroundColor Gray
+    } else {
+        Write-Host "      ✓ AWS CLI version is compatible" -ForegroundColor Green
+    }
+} else {
+    Write-Host "      ⚠ Could not parse AWS CLI version, continuing anyway..." -ForegroundColor Yellow
+}
+
+# Step 3: Check AgentCore availability in current region
+Write-Host "`n[3/7] Checking AgentCore availability in current region..." -ForegroundColor Yellow
+Write-Host "      (Verifying AgentCore service availability)" -ForegroundColor Gray
+# Detect current region from AWS CLI configuration
+$currentRegion = aws configure get region
+if ([string]::IsNullOrEmpty($currentRegion)) {
+    Write-Host "      ❌ No AWS region configured" -ForegroundColor Red
+    Write-Host ""
+    Write-Host "      Please configure your AWS region using:" -ForegroundColor Yellow
+    Write-Host "        aws configure set region <your-region>" -ForegroundColor Cyan
+    Write-Host ""
+    Write-Host "      For supported regions, see:" -ForegroundColor Gray
+    Write-Host "      https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-regions.html" -ForegroundColor Gray
+    exit 1
+}
+Write-Host "      Target region: $currentRegion" -ForegroundColor Gray
+
+# Try to list AgentCore runtimes to verify service availability
+$agentCoreCheck = aws bedrock-agentcore-control list-agent-runtimes --region $currentRegion --max-results 1 2>&1
+if ($LASTEXITCODE -ne 0) {
+    $errorMessage = $agentCoreCheck | Out-String
+    Write-Host "      ❌ AgentCore is not available in region: $currentRegion" -ForegroundColor Red
+    Write-Host ""
+    Write-Host "      Error details:" -ForegroundColor Gray
+    Write-Host "      $errorMessage" -ForegroundColor DarkGray
+    Write-Host ""
+    Write-Host "      For supported regions, see:" -ForegroundColor Gray
+    Write-Host "      https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-regions.html" -ForegroundColor Gray
+    exit 1
+}
+Write-Host "      ✓ AgentCore is available in $currentRegion" -ForegroundColor Green
+
+# Step 4: Check Python availability
+Write-Host "`n[4/7] Checking Python installation..." -ForegroundColor Yellow
+Write-Host "      (Required for running the agent locally)" -ForegroundColor Gray
 if (-not (Get-Command python -ErrorAction SilentlyContinue)) {
-    Write-Host "❌ Python 3 is required but not installed" -ForegroundColor Red
+    Write-Host "      ❌ Python 3.8+ is required but not installed" -ForegroundColor Red
+    Write-Host ""
+    Write-Host "      Please install Python 3.8 or later:" -ForegroundColor Yellow
+    Write-Host "        https://www.python.org/downloads/" -ForegroundColor Cyan
     exit 1
 }
 
-# Check if Node.js is available
+$pythonVersion = python --version 2>&1
+Write-Host "      ✓ $pythonVersion" -ForegroundColor Green
+
+# Step 5: Check Node.js availability
+Write-Host "`n[5/7] Checking Node.js installation..." -ForegroundColor Yellow
+Write-Host "      (Required for frontend development server)" -ForegroundColor Gray
 if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
-    Write-Host "❌ Node.js is required but not installed" -ForegroundColor Red
+    Write-Host "      ❌ Node.js 18+ is required but not installed" -ForegroundColor Red
+    Write-Host ""
+    Write-Host "      Please install Node.js 18 or later:" -ForegroundColor Yellow
+    Write-Host "        https://nodejs.org/en/download/" -ForegroundColor Cyan
     exit 1
 }
 
+$nodeVersion = node --version 2>&1
+Write-Host "      ✓ Node.js $nodeVersion" -ForegroundColor Green
+
+# Step 6: Install dependencies
+Write-Host "`n[6/7] Installing dependencies..." -ForegroundColor Yellow
+
 # Install agent dependencies if needed
-Write-Host "📦 Installing agent dependencies..." -ForegroundColor Yellow
+Write-Host "      Installing agent dependencies..." -ForegroundColor Gray
+Write-Host "      (bedrock-agentcore for local HTTP server, strands-agents framework, boto3 for AWS)" -ForegroundColor DarkGray
 if (-not (Test-Path "agent/venv")) {
-    Write-Host "Creating Python virtual environment..." -ForegroundColor Gray
+    Write-Host "      Creating Python virtual environment and installing dependencies..." -ForegroundColor DarkGray
     Push-Location agent
     python -m venv venv
     & "venv/Scripts/Activate.ps1"
     pip install -r requirements.txt
     Pop-Location
 } else {
-    Write-Host "Virtual environment already exists" -ForegroundColor Gray
+    Write-Host "      Virtual environment already exists" -ForegroundColor DarkGray
 }
 
 # Install frontend dependencies if needed
-Write-Host "📦 Installing frontend dependencies..." -ForegroundColor Yellow
+Write-Host "      Installing frontend dependencies..." -ForegroundColor Gray
 Push-Location frontend
 if (-not (Test-Path "node_modules")) {
     npm install
+} else {
+    Write-Host "      Frontend dependencies already installed" -ForegroundColor DarkGray
 }
 Pop-Location
 
 # Create local environment file for frontend
-Write-Host "⚙️  Setting up local environment..." -ForegroundColor Yellow
+Write-Host "      Setting up local environment configuration..." -ForegroundColor Gray
 
 # Remove any production environment file
 if (Test-Path "frontend/.env.production.local") {
@@ -49,37 +152,31 @@ VITE_LOCAL_DEV=true
 VITE_AGENT_RUNTIME_URL=/api
 "@ | Out-File -FilePath "frontend/.env.local" -Encoding UTF8
 
-Write-Host "Created local development environment configuration" -ForegroundColor Gray
+Write-Host "      ✓ Created local development environment configuration" -ForegroundColor Green
+
+# Step 7: Start services
+Write-Host "`n[7/7] Starting local development services..." -ForegroundColor Yellow
 
 Write-Host ""
-Write-Host "🎯 Starting services..." -ForegroundColor Green
 Write-Host "Backend will be available at: http://localhost:8080" -ForegroundColor Cyan
 Write-Host "Frontend will be available at: http://localhost:5173" -ForegroundColor Cyan
 Write-Host ""
+Write-Host "Development Workflow:" -ForegroundColor Yellow
+Write-Host "  • Changes to frontend\ files → Immediate hot reload" -ForegroundColor Gray
+Write-Host "  • Changes to agent\ files → Restart this script (Ctrl+C then re-run)" -ForegroundColor Gray
+Write-Host ""
 Write-Host "Press Ctrl+C to stop all services" -ForegroundColor Yellow
 Write-Host ""
 
 # Start AgentCore backend in background
-Write-Host "🔧 Starting AgentCore backend..." -ForegroundColor Blue
-
-# Check if AWS credentials are available
-$callerIdentity = aws sts get-caller-identity 2>&1
-if ($LASTEXITCODE -ne 0) {
-    Write-Host "⚠️  AWS credentials not found. The agent needs AWS credentials to call Bedrock." -ForegroundColor Yellow
-    Write-Host "Please configure AWS credentials using one of these methods:" -ForegroundColor Yellow
-    Write-Host "  1. aws configure" -ForegroundColor Cyan
-    Write-Host "  2. aws sso login --profile <profile-name>" -ForegroundColor Cyan
-    Write-Host "  3. Set environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY" -ForegroundColor Cyan
-    Write-Host ""
-    Write-Host "Press Enter to continue anyway, or Ctrl+C to exit and configure credentials first..." -ForegroundColor Yellow
-    Read-Host
-}
-
+Write-Host "Starting AgentCore backend..." -ForegroundColor Blue
 Push-Location agent
 & "venv/Scripts/Activate.ps1"
 $backendJob = Start-Job -ScriptBlock {
     Set-Location $using:PWD/agent
     & "venv/Scripts/Activate.ps1"
+    # Set UTF-8 encoding for Python to handle Unicode characters properly on Windows
+    $env:PYTHONIOENCODING = "utf-8"
     python strands_agent.py
 }
 Pop-Location
@@ -88,7 +185,7 @@ Pop-Location
 Start-Sleep -Seconds 3
 
 # Start frontend dev server in background
-Write-Host "🎨 Starting frontend dev server..." -ForegroundColor Magenta
+Write-Host "Starting frontend dev server..." -ForegroundColor Magenta
 Push-Location frontend
 $frontendJob = Start-Job -ScriptBlock {
     Set-Location $using:PWD/frontend
@@ -99,7 +196,7 @@ Pop-Location
 # Function to cleanup
 function Cleanup {
     Write-Host ""
-    Write-Host "🛑 Stopping services..." -ForegroundColor Red
+    Write-Host "`nStopping services..." -ForegroundColor Red
     Stop-Job $backendJob, $frontendJob -ErrorAction SilentlyContinue
     Remove-Job $backendJob, $frontendJob -ErrorAction SilentlyContinue
 }
