A full-stack multi-agent orchestration system demonstrating construction project management using AI agents. This project uses the analogy of a general contractor coordinating specialized trade agents to illustrate how complex, multi-agent AI systems can be designed and orchestrated.

Built with Strands Agents framework, Amazon Bedrock, React, and TypeScript.

Backend:

• Python 3.13+
• AWS Strands Agents framework
• Amazon Bedrock (Anthropic Claude LLMs)
• FastAPI + Uvicorn
• Pydantic for data validation
• MCP (Model Context Protocol) servers

Frontend:

• React 19
• TypeScript
• Vite (build tool)
• Tailwind CSS v3
• Zustand (state management)
• React Router
• Axios (API client)
• React Hot Toast (notifications)
• Lucide React (icons)

See the Architecture document for detailed system architecture diagrams and component details 🏗️

Get the system running locally in under 5 minutes!

• Python 3.13+ with uv package manager
• Node.js 18+ with npm
• AWS Credentials configured (access keys or AWS profile)

1. Clone and navigate to the project:

cd general-contractor-agent-demo

2. Set up Python environment:

# Install uv package manager (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Python dependencies
uv sync

# Optional: Update packages
uv lock --upgrade
uv sync

# Activate virtual environment
source .venv/bin/activate

3. Set up Node environment:

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Optional: Update packages
npm update

# Return to project root
cd ..

4. Configure environment variables:

# Copy example env file
cp .env.example .env

# Amazon Bedrock Configuration
# Authentication: Use AWS SSO login (aws sso login) with a profile, or use explicit credentials below
# Recommended: Use AWS_PROFILE for SSO-based authentication
# AWS_PROFILE=default

# Optional: Hardcode credentials (not recommended if using AWS SSO)
# AWS_ACCESS_KEY_ID="your-access-key-id"
# AWS_SECRET_ACCESS_KEY="your-secret-access-key"
# AWS_SESSION_TOKEN="your-session-token"

Example .env configuration:

DEFAULT_MODEL=us.anthropic.claude-sonnet-4-5-20250929-v1:0
TASK_TIMEOUT_SECONDS=120
MAX_CONSECUTIVE_TOOL_CALLS=3
MAX_TOTAL_TOOL_CALLS=20
MAX_IDENTICAL_CALLS=2
ENABLE_LOOP_DETECTION=true
LOG_LEVEL=INFO

Terminal 1 - Start Backend:

# From project root
uv run start.py

This starts:

• Materials Supplier MCP server
• Permitting Service MCP server
• FastAPI backend at http://localhost:8000

Terminal 2 - Start Frontend:

# In frontend directory
cd frontend
npm run dev

This starts the React frontend at http://localhost:5173

3. Open your browser:

Navigate to http://localhost:5173 to see the UI!

Try out pre-configured projects, such as the Kitchen Remodel (Template):

Complete kitchen renovation for a 12x18 feet space in modern style. Install new tile flooring throughout the kitchen. Install light-colored wood cabinets with marble countertops. Construct and install a kitchen island for food preparation. Install modern, stylish overhead lighting fixtures. Supply and install new kitchen appliances, including range, refrigerator, dishwasher, and microwave. All work to follow modern design aesthetic with coordinated finishes across flooring, cabinetry, and countertops. Include adequate electrical and plumbing rough-in for new appliances and island. You will need local permits. You must purchase materials from the materials supplier.

View example execution output →

Complete bathroom renovation for an 8x10 feet space in contemporary style. Remove all existing fixtures, flooring, and wall finishes. Install large-format porcelain tile flooring with slip-resistant finish. Install a new floating vanity with a light-colored wood finish and a solid-surface countertop with an integrated sink. Install a frameless glass shower enclosure with tiled shower walls and a built-in niche. Install a modern, water-efficient toilet and matching plumbing fixtures in a brushed metal finish. Install recessed ceiling lights and modern vanity lighting for task illumination. All work to follow contemporary design aesthetic with coordinated finishes across flooring, vanity, and fixtures. Include adequate electrical and plumbing rough-in for relocated vanity and shower controls. You will need local permits. You must purchase materials from the materials supplier.

Build a freestanding outdoor wood shed of approximately 8x12 feet for storing seasoned firewood and small yard equipment. Prepare and construct an appropriate foundation such as concrete piers or pressure-treated skids, sized and installed per local building requirements. Use treated lumber for floor framing and decking with gaps as appropriate to allow drainage and air movement under stacked wood. Frame walls with standard dimensional lumber and install weather-resistant siding and a sloped roof with shingles or metal panels to shed water away from the front. Provide a mostly open front with partial side walls, or a wide doorway, to allow easy stacking and removal of wood while maintaining protection from rain and snow. Include simple bracing and hardware to resist wind loads typical for the area. Ensure siting complies with setbacks, easements, and any fire separation requirements from structures. Exterior colors and materials to be simple and utilitarian while visually compatible with the yard. You will need local permits if required by local regulations. You must purchase materials from the materials supplier.

Or, use the Custom Project (Custom), such as:

Convert an existing basement room approximately 14x20 feet into a dedicated home theater in modern cinema style. Frame and insulate walls and ceiling as needed to improve sound isolation from the rest of the house. Install acoustically friendly wall and ceiling finishes, including acoustic panels or fabric-wrapped surfaces in key reflection areas. Construct a recessed front wall to accommodate a large projection screen, a wall-mounted TV, and front speakers. Build a raised rear seating platform for a second row of recliners. Install dimmable, layered lighting, including recessed ceiling cans, step lights on risers, and LED strip accent lighting. Rough-in and install all necessary electrical for AV equipment, including dedicated circuits, in-wall speaker wiring, conduit for HDMI/low-voltage runs, and equipment rack location. Provide HVAC adjustments or ducting as needed to maintain comfort without excessive noise. All finishes to follow a cohesive modern theater aesthetic with dark, low-reflectance colors. You will need local permits. You must purchase materials from the materials supplier.

Convert an open basement area approximately 12x18 feet into a dedicated home gym with durable, easy-to-clean finishes. Prepare and level the existing slab as needed and install high-impact rubber gym flooring throughout the space. Frame and finish walls as needed, using moisture-resistant materials in areas near exterior foundation walls. Install a full-height mirror wall along one long side of the room and a reinforced wall section or blocking for mounting a TV and wall-mounted fitness equipment. Provide blocking and structural support in ceiling and walls for future pull-up bars, suspension trainers, or heavy bag mounts as needed. Install bright, even LED overhead lighting suitable for workouts, along with sufficient general-purpose outlets around the room. Rough-in and install any required dedicated circuits for larger equipment such as a treadmill, rower, or stationary bike. Provide adequate ventilation or tie in to the existing HVAC system to maintain comfortable conditions during exercise. All finishes to match a clean, modern gym aesthetic with coordinated colors and materials. You will need local permits. You must purchase materials from the materials supplier.

Design a modern, weatherproof backyard dog house for a large breed (80–100 lb) with an insulated concrete slab and electric heated floor, a raised 4 ft x 3 ft interior sleeping area sized so the dog can stand, turn, and lie comfortably, and a covered front porch. Use a sturdy wood-framed structure with 2x4 studs, plywood sheathing, and rigid foam insulation in the walls, floor, and roof, plus a house wrap or vapor barrier. The roof should be a simple front-to-back sloped gable with a minimum 3/12 pitch, finished in dark asphalt shingles with proper overhangs and drip edges to prevent rain and snow. Include a single offset entrance with a heavy-duty vinyl flap to block wind, an interior temperature range of 45–60°F in winter, chew-resistant interior wall panels, and an exterior finish of stained horizontal wood siding that blends into a landscaped backyard setting in a cold-climate suburb. You have the authority to make any other decisions required to complete the project successfully.

Run the entire stack with Docker Compose - no local Python or Node.js installation required!

• Docker and Docker Compose installed
• AWS Credentials with Bedrock access

1. Configure environment variables:

# Copy example env file
cp .env.example .env

# Edit .env and add your AWS credentials (required for Docker)
AWS_ACCESS_KEY_ID=your_access_key_here
AWS_SECRET_ACCESS_KEY=your_secret_key_here
AWS_REGION=us-east-1

2. Build and start containers:

# Build and start all services
docker-compose up --build

# Or run in detached mode
docker-compose up --build -d

3. Access the application:

# View logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f backend
docker-compose logs -f materials
docker-compose logs -f permitting
docker-compose logs -f frontend

# Stop all services
docker-compose down

# Rebuild after code changes
docker-compose up --build

# Remove all containers and volumes
docker-compose down -v

┌──────────────────────────────────────────────────────────────────┐
│  Docker Compose Network (gc-network)                             │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────────┐         ┌─────────────────┐                 │
│  │    Frontend     │         │     Backend     │                 │
│  │   (nginx:80)    │────────▶│  (FastAPI:8000) │                 │
│  │   React App     │         │  Strands Agents │                 │
│  └────────┬────────┘         └────────┬────────┘                 │
│           │                           │                          │
│  localhost:3000                       │ HTTP (MCP Protocol)      │
│                           ┌───────────┴───────────┐              │
│                           ▼                       ▼              │
│              ┌─────────────────────┐ ┌─────────────────────┐     │
│              │  Materials MCP      │ │  Permitting MCP     │     │
│              │  (FastMCP:8080)     │ │  (FastMCP:8080)     │     │
│              └─────────────────────┘ └─────────────────────┘     │
│                        │                       │                 │
│               localhost:8081          localhost:8082             │
└──────────────────────────────────────────────────────────────────┘

Startup Order: MCP Servers → Backend → Frontend

The backend supports two modes for connecting to MCP servers:

Docker automatically uses MCP_MODE=http to connect to the containerized MCP servers.

Issue: Backend fails to start with AWS credentials error

• Solution: Ensure .env file has valid AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. Docker cannot use AWS SSO profiles.

Issue: Frontend can't connect to backend

• Solution: The frontend is built with VITE_API_URL=http://localhost:8000. Ensure backend is running and healthy.

Issue: MCP servers not starting

• Solution: Check MCP server logs with docker-compose logs materials permitting. Verify health endpoints respond.

Issue: Container keeps restarting

• Solution: Check logs with docker-compose logs backend to see error messages.

For detailed Docker documentation, see DOCKER.md.

Deploy the MCP servers and agents to AWS ECS (Elastic Container Service).

# Make scripts executable (one-time)
chmod +x deployment-ecs/**/*.sh

# Deploy Materials Supplier MCP to AWS
cd deployment-ecs/materials-supplier
./deploy.sh

# Deploy Permitting Service MCP to AWS
cd deployment-ecs/permitting-service
./deploy.sh

When your IP address changes, update all security groups:

# Dry run (preview changes)
./deployment-ecs/scripts/update-ip.sh --dry-run

# Apply changes
./deployment-ecs/scripts/update-ip.sh

# In .env file
MCP_MODE=http
MATERIALS_MCP_URL=http://your-materials-alb.us-east-1.elb.amazonaws.com/mcp
PERMITTING_MCP_URL=http://your-permitting-alb.us-east-1.elb.amazonaws.com/mcp

For detailed AWS deployment documentation, see deployment-ecs/README.md.

• Overview
• Key Features
• Architecture
• Frontend Dashboard
• Backend API
• Testing
• API Endpoints
• Project Types
• Development
• Troubleshooting
• Deployment Summary
• Documentation

This system models a construction project where a General Contractor agent orchestrates multiple specialized trade agents (Architect, Carpenter, Electrician, Plumber, Mason, Painter, HVAC, and Roofer). Each agent has specialized tools and expertise, and the General Contractor manages task dependencies, sequencing, and resource allocation.

• 8 Specialized Trade Agents: Each with domain-specific tools and expertise
• Task Dependency Management: Automatic sequencing based on construction workflows
• Phase-based Orchestration: Projects progress through multiple construction phases
• Material Management: Integrated building materials supplier MCP server
• Permitting System: Construction permit and inspection management MCP server
• Loop Detection: Prevents infinite loops with configurable thresholds
• Task Recovery: Skip or retry failed/stuck tasks to unblock projects
• Deadlock Prevention: Cascade failure propagation, circular dependency detection, and runtime deadlock breaking
• Automatic Retry: Timed-out tasks retry once with conciseness guidance before failing
• LLM Token Tracking: Per-project, per-agent, and per-task token usage metrics
• Bedrock API Call Counting: Tracks total and per-agent Bedrock API invocations
• Project Runtime Tracking: Measures wall-clock execution time for each project run
• REST API: Complete API for project management and monitoring
• Real-time Status Tracking: Monitor agent status, task progress, and project completion

• React + TypeScript: Modern, type-safe UI built with Vite
• Real-time Dashboard: Live updates every few second during task execution
• Live Activity Feed: Watch agents work in real-time with color-coded task cards
• Phase Progress Visualization: Track progress through 8 construction phases
• Task Management UI: Skip or retry failed tasks directly from the dashboard
• Project Templates: Pre-configured templates for common construction projects
• Responsive Design: Works on desktop and mobile with Tailwind CSS
• Toast Notifications: User feedback for all actions

┌─────────────────────────────────────────────────────────────┐
│                     React Frontend                          │
│  (Project Form, Dashboard, Live Activity Feed)              │
└──────────────────────┬──────────────────────────────────────┘
                       │ HTTP/REST API
                       ↓
┌─────────────────────────────────────────────────────────────┐
│                   FastAPI Backend                           │
│  - Project Management  - Task Execution                     │
│  - Agent Orchestration - Status Tracking                    │
└───────────────────────┬─────────────────────────────────────┘
                        │
        ┌───────────────┼─────────────────┐
        ↓               ↓                 ↓
┌──────────────┐ ┌─────────────┐ ┌──────────────────┐
│   General    │ │ Specialized │ │   MCP Servers    │
│  Contractor  │ │   Agents    │ │ - Materials      │
│(Orchestrator)│ │ (8 Trades)  │ │ - Permitting     │
└──────────────┘ └─────────────┘ └──────────────────┘

• Central orchestration agent powered by Amazon Bedrock and Anthropic Claude
• Manages task sequencing and dependencies
• Delegates work to specialized trade agents
• Integrates with MCP servers for materials and permits

• Architect Agent (design & planning)
• Carpenter Agent (framing, cabinetry, finishing)
• Electrician Agent (wiring, fixtures)
• Plumber Agent (pipes, fixtures)
• Mason Agent (concrete, masonry)
• Painter Agent (painting, finishing)
• HVAC Agent (heating, cooling systems)
• Roofer Agent (roofing, gutters)

Two MCP servers provide external service integration:

1. Materials Supplier Server

   • Tools: check_availability, order_materials, get_catalog, get_order
   • Manages inventory, pricing, and material ordering
   • Categories: lumber, electrical, plumbing, masonry, paint, HVAC, roofing

2. Permitting Service Server

   • Tools: apply_for_permit, check_permit_status, schedule_inspection, get_required_permits, get_inspection
   • Handles construction permits and inspections
   • Permit types: building, electrical, plumbing, mechanical, demolition, roofing

Transport Modes:

• Manages task dependencies and sequencing
• Tracks task states: pending, ready, in_progress, completed, failed
• Supports 8 construction phases: planning, permitting, foundation, framing, rough_in, inspection, finishing, final_inspection

The React frontend provides a comprehensive real-time view of your construction project:

• Choose from pre-configured project templates (Kitchen, Bathroom, Shed, etc.)
• Or describe a custom project with dynamic planning
• Configure project parameters and submit

1. Auto-Refresh Indicator

   • Shows "🔴 LIVE" when tasks are in progress
   • Updates every few seconds for real-time feedback
   • Manual refresh button available

2. Stats Cards

   • Completion percentage
   • Tasks in progress
   • Completed/Total tasks
   • Failed tasks count

3. Phase Progress Bar

   • Visual representation of 8 construction phases
   • Color-coded: green (completed), blue (current), gray (upcoming)
   • Shows current phase name

4. Live Activity Feed (scrollable, 600px height)

   • Blue cards (pulsing): Agents currently working
   • Green cards: Completed tasks (most recent first)
   • Yellow cards: Queued tasks waiting to start

5. Control Buttons

   • Refresh: Manual data refresh
   • Reset: Clear project and start over

The backend provides a complete REST API for project management:

API Documentation (when server is running):

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

• POST /api/projects/start - Start a new project
• POST /api/projects/execute-next-phase - Execute next phase
• POST /api/projects/execute-all - Execute entire project
• GET /api/projects/status - Get project status
• POST /api/projects/reset - Reset for new project

• GET /api/tasks - Get all tasks
• GET /api/tasks/{task_id} - Get specific task
• POST /api/tasks/{task_id}/skip - Skip failed task
• POST /api/tasks/{task_id}/retry - Retry failed task

• GET /api/agents - List all agents
• GET /api/agents/status - Get all agents' status
• GET /api/agents/{agent_name} - Get specific agent status

• GET /api/materials/catalog - Browse materials
• POST /api/materials/order - Order materials
• POST /api/permits/apply - Apply for permit
• POST /api/permits/inspections - Schedule inspection

For detailed instructions, see Amazon Bedrock Model Access Documentation.

# Run shed construction demo with simulated output
uv run tests/test_shed_demo.py

Shows:

• Real-time agent reasoning
• Tool calls with inputs
• Tool execution results
• Task-by-task progress

Perfect for seeing how the system works without AWS setup!

# See complete task breakdown and dependencies
uv run tests/test_shed_detailed.py

Shows:

• All 10 tasks for building a shed
• Task dependencies and phases
• Materials and requirements
• Agent workload distribution

# Test a single agent with Amazon Bedrock
uv run tests/test_agent.py

Verifies:

• AWS credentials configured correctly
• Bedrock access working
• Strands Agents framework setup

# Execute with real Claude AI agents
uv run tests/test_shed_detailed.py execute

Shows live streaming of:

• Real Claude AI agent reasoning
• Actual tool calls and results
• Complete project execution (5-10 minutes)

# Test MCP servers
uv run tests/test_mcp_integration.py

Tests:

• Materials supplier MCP server
• Permitting service MCP server
• Full integration scenarios

The system supports pre-configured project templates with automatic task sequencing:

• Architectural design
• Permit application
• Demolition
• Plumbing & electrical rough-in
• Inspection
• Cabinet installation
• Fixture installation
• Painting
• Final inspection

• Design and planning
• Permitting
• Demolition
• Plumbing & electrical work
• Drywall and finishing
• Fixture installation
• Final inspection

• Architectural plans
• Foundation (concrete slab)
• Framing (walls and roof)
• Roofing installation
• Electrical wiring
• Siding and exterior
• Painting
• Final walkthrough

• Architectural plans
• Building permits
• Foundation
• Framing
• Roofing
• Systems (electrical, plumbing, HVAC)
• Inspections
• Finishing work
• Final inspection

• Design
• Permits
• Foundation
• Framing
• Roof extension
• System integration
• Finishing

Enable dynamic planning for custom project descriptions.

AI agents can sometimes get stuck in infinite loops, repeatedly calling the same tool with the same parameters. Custom (dynamically planned) projects can also deadlock when a failed task permanently blocks all dependent tasks.

# Maximum consecutive identical tool calls before stopping
MAX_CONSECUTIVE_TOOL_CALLS=3

# Maximum total tool calls for a single task
MAX_TOTAL_TOOL_CALLS=20

# Maximum identical calls with same parameters
MAX_IDENTICAL_CALLS=2

# Enable/disable loop detection
ENABLE_LOOP_DETECTION=true

# Timeout per task in seconds
TASK_TIMEOUT_SECONDS=120  # 60 for testing, 300 for production

# Number of retries for timed-out tasks before marking as failed
MAX_TASK_RETRIES=1

When a task times out, the system retries it once with guidance to be more concise before marking it as permanently failed.

Custom projects using dynamic planning have additional safeguards:

• Cascade Failure: When a task fails, all directly and transitively dependent tasks are automatically marked as failed with context, preventing indefinite blocking
• Circular Dependency Detection: DFS-based cycle detection runs at plan creation time and breaks any circular references
• Invalid Dependency Cleanup: Dependencies referencing non-existent task IDs are stripped during plan validation
• Unresolvable Dependency Detection: Tasks waiting on failed or missing dependencies are auto-failed at runtime
• Runtime Deadlock Breaker: During execution, tasks stuck because their unmet dependencies are only other pending tasks are force-unblocked
• READY-State Recovery: Tasks already transitioned to READY status are always included in scheduling, preventing phase-filtering from orphaning them

The dynamic planning agent is constrained to produce focused, single-purpose tasks:

• Each task must describe a single focused action (not combined inspections or multi-step activities)
• Task descriptions must be under 200 characters
• Inspection tasks are broken into separate tasks per system

Agents receive explicit loop prevention instructions:

IMPORTANT CONSTRAINTS:
- Do NOT call the same tool more than 3 times in a row
- If a tool fails, try a different approach instead of repeating
- Each tool should be called AT MOST ONCE unless necessary

general-contractor-agent-demo/
├── backend/
│   ├── agents/              # 8 specialized trade agents
│   ├── mcp_servers/         # MCP servers - stdio mode (local dev)
│   ├── orchestration/       # Task manager and dependencies
│   ├── api/                 # FastAPI routes
│   ├── utils/               # Loop detection, token tracking utilities
│   ├── config.py            # Configuration settings
│   └── Dockerfile           # Backend container
├── frontend/
│   ├── src/
│   │   ├── components/      # React components (Dashboard, Form, etc.)
│   │   ├── api/             # API client
│   │   ├── hooks/           # Custom React hooks
│   │   ├── store/           # Zustand state management
│   │   ├── types/           # TypeScript type definitions
│   │   └── App.tsx          # Main app with routing
│   ├── Dockerfile           # Frontend container
│   ├── nginx.conf           # nginx configuration
│   └── package.json
├── docker/
│   ├── materials-mcp/       # Materials MCP Docker build
│   └── permitting-mcp/      # Permitting MCP Docker build
├── deployment-ecs/
│   ├── materials-supplier/  # AWS deployment for Materials MCP
│   ├── permitting-service/  # AWS deployment for Permitting MCP
│   ├── backend-runtime/     # AWS ECS backend deployment
│   ├── scripts/             # Utility scripts (update-ip.sh)
│   └── README.md            # Deployment documentation
├── tests/                   # Test scripts and demos
├── docs/                    # Documentation
├── docker-compose.yaml      # 4-container local stack
├── start.py                 # Unified startup script (local dev)
├── pyproject.toml           # Python dependencies
└── .env                     # Environment configuration

1. Create agent file in backend/agents/ (e.g., landscaper.py)
2. Define tools using @tool decorator
3. Create agent factory function with system_prompt and tools
4. Register in backend/agents/__init__.py
5. Add to GeneralContractor agent pool
6. Create tasks that use the new agent

Example structure:

from strands import Agent, tool
from strands.models import BedrockModel

@tool
def plant_trees(input: PlantTreesInput) -> dict:
    """Plant trees in the yard."""
    return {"status": "success", "details": f"Planted {input.tree_count} trees"}

def create_landscaper_agent() -> Agent:
    # Configure model and create agent
    return Agent(
        model=model,
        system_prompt="You are an expert Landscaper...",
        tools=[plant_trees],
    )

1. Add task generation method in backend/orchestration/task_manager.py
2. Register project type in create_project_tasks()
3. Add to frontend project type options in frontend/src/components/ProjectForm.tsx
4. Create test script to demonstrate new project type

Install dev dependencies:

uv sync --extra dev

Format code:

black . && isort . && autoflake --in-place --recursive .

Lint code:

flake8 backend/ tests/ && mypy backend/

Lint code:

cd frontend && npm run lint

Auto-fix linting issues:

cd frontend && npm run lint:fix

Issue: Module 'backend' not found

• Solution: Run from project root directory

Issue: AWS credentials not found

• Solution: Ensure .env exists with AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY or AWS_PROFILE

Issue: AccessDeniedException when invoking Bedrock

• Solution:
  • Enable Claude Sonnet 4.5 in Amazon Bedrock console
  • Verify IAM permissions include bedrock:InvokeModel
  • Confirm correct region (default: us-east-1)

Issue: ValidationException: Invalid model identifier

• Solution: Use inference profile format in .env:

  DEFAULT_MODEL=us.anthropic.claude-sonnet-4-5-20250929-v1:0
  

Issue: Port 8000 already in use

• Solution: Change API_PORT in .env or stop other service using port 8000

Issue: Frontend shows blank page

• Solution: Check browser console for errors, verify backend is running, check API_PORT matches

Issue: Tasks stuck in infinite loops

• Solution:
  • Verify loop detection is enabled in .env
  • Reduce TASK_TIMEOUT_SECONDS to fail faster
  • Use Skip button in dashboard to unblock project

See 🐳 Running with Docker and ☁️ AWS Deployment for details.

• ARCHITECTURE.md - System architecture diagrams and component details 🏗️
• QUICKSTART.md - Quick start guide and test script overview
• DOCKER.md - Docker deployment guide 🐳
• deployment-ecs/README.md - AWS ECS deployment guide ☁️
• EXECUTION_GUIDE.md - Detailed execution mode guide
• DYNAMIC_PLANNING.md - Dynamic task planning for custom projects
• LOOP_PROTECTION.md - Loop detection and prevention ⚠️
• EXAMPLE_PROJECTS.md - Sample project descriptions to test with 📝
• API Documentation - http://localhost:8000/docs (when server running)

The included test scripts demonstrate building a 10×12 ft storage shed:

Project Specifications:

• Dimensions: 10 ft × 12 ft × 8 ft (height)
• Foundation: Concrete slab (120 sq ft)
• Structure: Wood frame with asphalt shingle roof
• Features: 1 entry door, 1 window, electrical (1 outlet + 1 light)
• Finish: Exterior paint

Task Flow (10 tasks across 6 phases):

1. Planning: Architect designs shed plans
2. Foundation: Mason pours concrete slab
3. Framing: Carpenter frames walls and roof trusses
4. Rough-in: Roofer installs roofing, Electrician wires electrical
5. Finishing: Carpenter installs siding/door/window, Painter finishes exterior
6. Final Inspection: Carpenter performs walkthrough

Run demo: uv run tests/test_shed_demo.py

This project is for educational and training purposes.

This is a training workshop project. Feedback and suggestions are welcome!

• Built with Strands Agents framework
• Powered by Claude via Amazon Bedrock
• Inspired by real-world construction project management
• Designed to demonstrate multi-agent AI orchestration patterns

For questions or issues, please open an issue on the GitHub repository.

Need help getting started? Check out QUICKSTART.md!