feat: centralize port defaults and make ports configurable via env vars

- Add centralized port constants (DEFAULT_ACP_PORT, DEFAULT_TEMPORAL_PORT, etc.)
  in environment_variables.py to eliminate magic numbers across the codebase
- Fix deploy_handlers.py to use ACP_PORT env var instead of hardcoded 8718
- Fix cleanup_handlers.py to use TEMPORAL_ADDRESS env var for Temporal connections
- Fix run_handlers.py to respect TEMPORAL_ADDRESS and REDIS_URL env var overrides
- Fix base_acp_server.py run() to read port from ACP_PORT env var
- Fix worker.py to use centralized DEFAULT_TEMPORAL_ADDRESS fallback
- Fix debug_config.py and debug.py to use DEFAULT_DEBUG_PORT constant
- Update all 7 CLI manifest templates with improved port configurability docs
- Update multi-agent start-agents.sh to support env var port overrides

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: SWE Destroyer

examples/tutorials/10_async/00_base/090_multi_agent_non_temporal/start-agents.sh

@@ -11,11 +11,11 @@ YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
 NC='\033[0m' # No Color
 
-# Configuration
-ORCHESTRATOR_PORT=8718
-CREATOR_PORT=8719
-CRITIC_PORT=8720
-FORMATTER_PORT=8721
+# Configuration - override with environment variables if needed
+ORCHESTRATOR_PORT=${ORCHESTRATOR_PORT:-8718}
+CREATOR_PORT=${CREATOR_PORT:-8719}
+CRITIC_PORT=${CRITIC_PORT:-8720}
+FORMATTER_PORT=${FORMATTER_PORT:-8721}
 
 # Base directory
 BASE_DIR="examples/tutorials/10_async/00_base/090_multi_agent_non_temporal"
@@ -199,7 +199,7 @@ test_system() {
     # Check if agents are responding on their ports
     echo -e "${YELLOW}🔍 Testing agent connectivity...${NC}"
 
-    ports=(8718 8719 8720 8721)
+    ports=($ORCHESTRATOR_PORT $CREATOR_PORT $CRITIC_PORT $FORMATTER_PORT)
     agents=("orchestrator" "creator" "critic" "formatter")
     all_responding=true
 
@@ -223,10 +223,10 @@ test_system() {
         echo "   3. Use direct HTTP calls to test individual agents"
         echo ""
         echo -e "${BLUE}🔗 Agent Endpoints:${NC}"
-        echo "   • Orchestrator: http://localhost:8718"
-        echo "   • Creator: http://localhost:8719"
-        echo "   • Critic: http://localhost:8720"
-        echo "   • Formatter: http://localhost:8721"
+        echo "   • Orchestrator: http://localhost:$ORCHESTRATOR_PORT"
+        echo "   • Creator: http://localhost:$CREATOR_PORT"
+        echo "   • Critic: http://localhost:$CRITIC_PORT"
+        echo "   • Formatter: http://localhost:$FORMATTER_PORT"
         echo ""
         echo -e "${BLUE}📝 Sample Request (send via AgentEx UI):${NC}"
         echo '{"request": "Write a brief welcome message for our new AI assistant", "rules": ["Under 100 words", "Friendly tone", "Include emoji"], "target_format": "HTML"}'
@@ -262,10 +262,10 @@ case "${1:-start}" in
         echo "  $0 stop      - Stop all agents"
         echo ""
         echo -e "${BLUE}📤 Agent Endpoints:${NC}"
-        echo "  • Orchestrator: http://localhost:8718"
-        echo "  • Creator: http://localhost:8719"
-        echo "  • Critic: http://localhost:8720"
-        echo "  • Formatter: http://localhost:8721"
+        echo "  • Orchestrator: http://localhost:$ORCHESTRATOR_PORT"
+        echo "  • Creator: http://localhost:$CREATOR_PORT"
+        echo "  • Critic: http://localhost:$CRITIC_PORT"
+        echo "  • Formatter: http://localhost:$FORMATTER_PORT"
         echo ""
         echo -e "${BLUE}💡 To interact with agents:${NC}"
         echo "  1. Use the AgentEx platform to send tasks"

src/agentex/lib/cli/commands/agents.py

@@ -13,6 +13,7 @@
 from agentex.lib.cli.debug import DebugMode, DebugConfig
 from agentex.lib.utils.logging import make_logger
 from agentex.lib.cli.utils.cli_utils import handle_questionary_cancellation
+from agentex.lib.environment_variables import DEFAULT_DEBUG_PORT
 from agentex.lib.sdk.config.validation import (
     EnvironmentsValidationError,
     generate_helpful_error_message,
@@ -269,7 +270,9 @@ def run(
     debug: bool = typer.Option(False, help="Enable debug mode for both worker and ACP (disables auto-reload)"),
     debug_worker: bool = typer.Option(False, help="Enable debug mode for temporal worker only"),
     debug_acp: bool = typer.Option(False, help="Enable debug mode for ACP server only"),
-    debug_port: int = typer.Option(5678, help="Port for remote debugging (worker uses this, ACP uses port+1)"),
+    debug_port: int = typer.Option(
+        DEFAULT_DEBUG_PORT, help="Port for remote debugging (worker uses this, ACP uses port+1)"
+    ),
     wait_for_debugger: bool = typer.Option(False, help="Wait for debugger to attach before starting"),
 ) -> None:
     """

src/agentex/lib/cli/debug/debug_config.py

@@ -6,10 +6,12 @@
 from enum import Enum
 
 from agentex.lib.utils.model_utils import BaseModel
+from agentex.lib.environment_variables import DEFAULT_DEBUG_PORT
 
 
 class DebugMode(str, Enum):
     """Debug mode options"""
+
     WORKER = "worker"
     ACP = "acp"
     BOTH = "both"
@@ -18,91 +20,73 @@ class DebugMode(str, Enum):
 
 class DebugConfig(BaseModel):
     """Configuration for debug mode"""
-    
+
     enabled: bool = False
     mode: DebugMode = DebugMode.NONE
-    port: int = 5678
+    port: int = DEFAULT_DEBUG_PORT
     wait_for_attach: bool = False
     auto_port: bool = True  # Automatically find available port if specified port is busy
-    
+
     @classmethod
     def create_worker_debug(
-        cls, 
-        port: int = 5678, 
-        wait_for_attach: bool = False,
-        auto_port: bool = True
+        cls, port: int = DEFAULT_DEBUG_PORT, wait_for_attach: bool = False, auto_port: bool = True
     ) -> "DebugConfig":
         """Create debug config for worker debugging"""
-        return cls(
-            enabled=True,
-            mode=DebugMode.WORKER,
-            port=port,
-            wait_for_attach=wait_for_attach,
-            auto_port=auto_port
-        )
-    
+        return cls(enabled=True, mode=DebugMode.WORKER, port=port, wait_for_attach=wait_for_attach, auto_port=auto_port)
+
     @classmethod
     def create_acp_debug(
-        cls, 
-        port: int = 5679, 
-        wait_for_attach: bool = False,
-        auto_port: bool = True
+        cls, port: int = DEFAULT_DEBUG_PORT + 1, wait_for_attach: bool = False, auto_port: bool = True
     ) -> "DebugConfig":
         """Create debug config for ACP debugging"""
-        return cls(
-            enabled=True,
-            mode=DebugMode.ACP,
-            port=port,
-            wait_for_attach=wait_for_attach,
-            auto_port=auto_port
-        )
-    
+        return cls(enabled=True, mode=DebugMode.ACP, port=port, wait_for_attach=wait_for_attach, auto_port=auto_port)
+
     @classmethod
     def create_both_debug(
-        cls, 
-        worker_port: int = 5678,
-        _acp_port: int = 5679,
+        cls,
+        worker_port: int = DEFAULT_DEBUG_PORT,
+        _acp_port: int = DEFAULT_DEBUG_PORT + 1,
         wait_for_attach: bool = False,
-        auto_port: bool = True
+        auto_port: bool = True,
     ) -> "DebugConfig":
         """Create debug config for both worker and ACP debugging"""
         return cls(
             enabled=True,
             mode=DebugMode.BOTH,
             port=worker_port,  # Primary port for worker
             wait_for_attach=wait_for_attach,
-            auto_port=auto_port
+            auto_port=auto_port,
         )
-    
+
     def should_debug_worker(self) -> bool:
         """Check if worker should be debugged"""
         return self.enabled and self.mode in (DebugMode.WORKER, DebugMode.BOTH)
-    
+
     def should_debug_acp(self) -> bool:
         """Check if ACP should be debugged"""
         return self.enabled and self.mode in (DebugMode.ACP, DebugMode.BOTH)
-    
+
     def get_worker_port(self) -> int:
         """Get port for worker debugging"""
         return self.port
-    
+
     def get_acp_port(self) -> int:
         """Get port for ACP debugging"""
         if self.mode == DebugMode.BOTH:
             return self.port + 1  # Use port + 1 for ACP when debugging both
         return self.port
 
 
-def find_available_port(start_port: int = 5678, max_attempts: int = 10) -> int:
+def find_available_port(start_port: int = DEFAULT_DEBUG_PORT, max_attempts: int = 10) -> int:
     """Find an available port starting from start_port"""
     for port in range(start_port, start_port + max_attempts):
         try:
             with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-                s.bind(('localhost', port))
+                s.bind(("localhost", port))
                 return port
         except OSError:
             continue
-    
+
     # If we can't find an available port, just return the start port
     # and let the debug server handle the error
     return start_port
@@ -112,4 +96,4 @@ def resolve_debug_port(config: DebugConfig, target_port: int) -> int:
     """Resolve the actual port to use for debugging"""
     if config.auto_port:
         return find_available_port(target_port)
-    return target_port 
+    return target_port