signalwire-agents 0.1.9__py3-none-any.whl → 0.1.11__py3-none-any.whl

signalwire_agents/core/agent_base.py

@@ -21,6 +21,9 @@ import base64
 import logging
 import inspect
 import functools
+import re
+import signal
+import sys
 from typing import Optional, Union, List, Dict, Any, Tuple, Callable, Type
 from urllib.parse import urlparse, urlencode
 
@@ -51,11 +54,11 @@ try:
                 structlog.stdlib.add_logger_name,
                 structlog.stdlib.add_log_level,
                 structlog.stdlib.PositionalArgumentsFormatter(),
-                structlog.processors.TimeStamper(fmt="iso"),
+                structlog.processors.TimeStamper(fmt="%Y-%m-%d %H:%M:%S"),
                 structlog.processors.StackInfoRenderer(),
                 structlog.processors.format_exc_info,
                 structlog.processors.UnicodeDecoder(),
-                structlog.processors.JSONRenderer()
+                structlog.dev.ConsoleRenderer()
             ],
             context_class=dict,
             logger_factory=structlog.stdlib.LoggerFactory(),
@@ -76,6 +79,8 @@ from signalwire_agents.core.state import StateManager, FileStateManager
 from signalwire_agents.core.swml_service import SWMLService
 from signalwire_agents.core.swml_handler import AIVerbHandler
 from signalwire_agents.core.skill_manager import SkillManager
+from signalwire_agents.utils.schema_utils import SchemaUtils
+from signalwire_agents.utils.serverless import get_execution_mode, is_serverless_mode
 
 # Create a logger
 logger = structlog.get_logger("agent_base")
@@ -282,7 +287,9 @@ class AgentBase(SWMLService):
         agent_id: Optional[str] = None,
         native_functions: Optional[List[str]] = None,
         schema_path: Optional[str] = None,
-        suppress_logs: bool = False
+        suppress_logs: bool = False,
+        enable_post_prompt_override: bool = False,
+        check_for_input_override: bool = False
     ):
         """
         Initialize a new agent
@@ -306,6 +313,8 @@ class AgentBase(SWMLService):
             native_functions: Optional list of native functions to include in the SWAIG object
             schema_path: Optional path to the schema file
             suppress_logs: Whether to suppress structured logs
+            enable_post_prompt_override: Whether to enable post-prompt override
+            check_for_input_override: Whether to enable check-for-input override
         """
         # Import SWMLService here to avoid circular imports
         from signalwire_agents.core.swml_service import SWMLService
@@ -325,7 +334,7 @@ class AgentBase(SWMLService):
         
         # Log the schema path if found and not suppressing logs
         if self.schema_utils and self.schema_utils.schema_path and not suppress_logs:
-            print(f"Using schema.json at: {self.schema_utils.schema_path}")
+            self.log.debug("using_schema_path", path=self.schema_utils.schema_path)
         
         # Setup logger for this instance
         self.log = logger.bind(agent=name)
@@ -360,7 +369,7 @@ class AgentBase(SWMLService):
             self.pom = None
         
         # Initialize tool registry (separate from SWMLService verb registry)
-        self._swaig_functions: Dict[str, SWAIGFunction] = {}
+        self._swaig_functions = {}
         
         # Initialize session manager
         self._session_manager = SessionManager(token_expiry_secs=token_expiry_secs)
@@ -408,6 +417,15 @@ class AgentBase(SWMLService):
         
         # Initialize skill manager
         self.skill_manager = SkillManager(self)
+        
+        # Initialize contexts system
+        self._contexts_builder = None
+        self._contexts_defined = False
+        
+        self.schema_utils = SchemaUtils(schema_path)
+        if self.schema_utils and self.schema_utils.schema:
+            self.log.debug("schema_loaded", path=self.schema_utils.schema_path)
+        
     
     def _process_prompt_sections(self):
         """
@@ -510,6 +528,39 @@ class AgentBase(SWMLService):
     # Prompt Building Methods
     # ----------------------------------------------------------------------
     
+    def define_contexts(self) -> 'ContextBuilder':
+        """
+        Define contexts and steps for this agent (alternative to POM/prompt)
+        
+        Returns:
+            ContextBuilder for method chaining
+            
+        Note:
+            Contexts can coexist with traditional prompts. The restriction is only
+            that you can't mix POM sections with raw text in the main prompt.
+        """
+        # Import here to avoid circular imports
+        from signalwire_agents.core.contexts import ContextBuilder
+        
+        if self._contexts_builder is None:
+            self._contexts_builder = ContextBuilder(self)
+            self._contexts_defined = True
+        
+        return self._contexts_builder
+    
+    def _validate_prompt_mode_exclusivity(self):
+        """
+        Validate that POM sections and raw text are not mixed in the main prompt
+        
+        Note: This does NOT prevent contexts from being used alongside traditional prompts
+        """
+        # Only check for mixing POM sections with raw text in the main prompt
+        if self._raw_prompt and (self.pom and hasattr(self.pom, 'sections') and self.pom.sections):
+            raise ValueError(
+                "Cannot mix raw text prompt with POM sections in the main prompt. "
+                "Use either set_prompt_text() OR prompt_add_section() methods, not both."
+            )
+    
     def set_prompt_text(self, text: str) -> 'AgentBase':
         """
         Set the prompt as raw text instead of using POM
@@ -520,6 +571,7 @@ class AgentBase(SWMLService):
         Returns:
             Self for method chaining
         """
+        self._validate_prompt_mode_exclusivity()
         self._raw_prompt = text
         return self
     
@@ -575,6 +627,7 @@ class AgentBase(SWMLService):
         Returns:
             Self for method chaining
         """
+        self._validate_prompt_mode_exclusivity()
         if self._use_pom and self.pom:
             # Create parameters for add_section based on what's supported
             kwargs = {}
@@ -690,7 +743,9 @@ class AgentBase(SWMLService):
         parameters: Dict[str, Any], 
         handler: Callable,
         secure: bool = True,
-        fillers: Optional[Dict[str, List[str]]] = None
+        fillers: Optional[Dict[str, List[str]]] = None,
+        webhook_url: Optional[str] = None,
+        **swaig_fields
     ) -> 'AgentBase':
         """
         Define a SWAIG function that the AI can call
@@ -702,6 +757,8 @@ class AgentBase(SWMLService):
             handler: Function to call when invoked
             secure: Whether to require token validation
             fillers: Optional dict mapping language codes to arrays of filler phrases
+            webhook_url: Optional external webhook URL to use instead of local handling
+            **swaig_fields: Additional SWAIG fields to include in function definition
             
         Returns:
             Self for method chaining
@@ -715,10 +772,34 @@ class AgentBase(SWMLService):
             parameters=parameters,
             handler=handler,
             secure=secure,
-            fillers=fillers
+            fillers=fillers,
+            webhook_url=webhook_url,
+            **swaig_fields
         )
         return self
     
+    def register_swaig_function(self, function_dict: Dict[str, Any]) -> 'AgentBase':
+        """
+        Register a raw SWAIG function dictionary (e.g., from DataMap.to_swaig_function())
+        
+        Args:
+            function_dict: Complete SWAIG function definition dictionary
+            
+        Returns:
+            Self for method chaining
+        """
+        function_name = function_dict.get('function')
+        if not function_name:
+            raise ValueError("Function dictionary must contain 'function' field with the function name")
+            
+        if function_name in self._swaig_functions:
+            raise ValueError(f"Tool with name '{function_name}' already exists")
+        
+        # Store the raw function dictionary for data_map tools
+        # These don't have handlers since they execute on SignalWire's server
+        self._swaig_functions[function_name] = function_dict
+        return self
+    
     def _tool_decorator(self, name=None, **kwargs):
         """
         Decorator for defining SWAIG tools in a class
@@ -734,10 +815,11 @@ class AgentBase(SWMLService):
             if name is None:
                 name = func.__name__
                 
-            parameters = kwargs.get("parameters", {})
-            description = kwargs.get("description", func.__doc__ or f"Function {name}")
-            secure = kwargs.get("secure", True)
-            fillers = kwargs.get("fillers", None)
+            parameters = kwargs.pop("parameters", {})
+            description = kwargs.pop("description", func.__doc__ or f"Function {name}")
+            secure = kwargs.pop("secure", True)
+            fillers = kwargs.pop("fillers", None)
+            webhook_url = kwargs.pop("webhook_url", None)
             
             self.define_tool(
                 name=name,
@@ -745,7 +827,9 @@ class AgentBase(SWMLService):
                 parameters=parameters,
                 handler=func,
                 secure=secure,
-                fillers=fillers
+                fillers=fillers,
+                webhook_url=webhook_url,
+                **kwargs  # Pass through any additional swaig_fields
             )
             return func
         return decorator
@@ -772,20 +856,24 @@ class AgentBase(SWMLService):
                     tool_name = getattr(attr, "_tool_name", name)
                     tool_params = getattr(attr, "_tool_params", {})
                     
-                    # Get description and parameters
-                    description = tool_params.get("description", attr.__doc__ or f"Function {tool_name}")
-                    parameters = tool_params.get("parameters", {})
-                    secure = tool_params.get("secure", True)
-                    fillers = tool_params.get("fillers", None)
+                    # Extract known parameters and pass through the rest as swaig_fields
+                    tool_params_copy = tool_params.copy()
+                    description = tool_params_copy.pop("description", attr.__doc__ or f"Function {tool_name}")
+                    parameters = tool_params_copy.pop("parameters", {})
+                    secure = tool_params_copy.pop("secure", True)
+                    fillers = tool_params_copy.pop("fillers", None)
+                    webhook_url = tool_params_copy.pop("webhook_url", None)
                     
-                    # Register the tool
+                    # Register the tool with any remaining params as swaig_fields
                     self.define_tool(
                         name=tool_name,
                         description=description,
                         parameters=parameters,
                         handler=attr.__get__(self, cls),  # Bind the method to this instance
                         secure=secure,
-                        fillers=fillers
+                        fillers=fillers,
+                        webhook_url=webhook_url,
+                        **tool_params_copy  # Pass through any additional swaig_fields
                     )
     
     @classmethod
@@ -812,12 +900,102 @@ class AgentBase(SWMLService):
     
     def get_name(self) -> str:
         """
-        Get the agent name
+        Get agent name
         
         Returns:
-            Agent name/identifier
+            Agent name
         """
         return self.name
+
+    def get_app(self):
+        """
+        Get the FastAPI application instance for deployment adapters like Lambda/Mangum
+        
+        This method ensures the FastAPI app is properly initialized and configured,
+        then returns it for use with deployment adapters like Mangum for AWS Lambda.
+        
+        Returns:
+            FastAPI: The configured FastAPI application instance
+        """
+        if self._app is None:
+            # Initialize the app if it hasn't been created yet
+            # This follows the same initialization logic as serve() but without running uvicorn
+            from fastapi import FastAPI
+            from fastapi.middleware.cors import CORSMiddleware
+            
+            # Create a FastAPI app with explicit redirect_slashes=False
+            app = FastAPI(redirect_slashes=False)
+            
+            # Add health and ready endpoints directly to the main app to avoid conflicts with catch-all
+            @app.get("/health")
+            @app.post("/health")
+            async def health_check():
+                """Health check endpoint for Kubernetes liveness probe"""
+                return {
+                    "status": "healthy",
+                    "agent": self.get_name(),
+                    "route": self.route,
+                    "functions": len(self._swaig_functions)
+                }
+            
+            @app.get("/ready")
+            @app.post("/ready")
+            async def readiness_check():
+                """Readiness check endpoint for Kubernetes readiness probe"""
+                return {
+                    "status": "ready",
+                    "agent": self.get_name(),
+                    "route": self.route,
+                    "functions": len(self._swaig_functions)
+                }
+            
+            # Add CORS middleware if needed
+            app.add_middleware(
+                CORSMiddleware,
+                allow_origins=["*"],
+                allow_credentials=True,
+                allow_methods=["*"],
+                allow_headers=["*"],
+            )
+            
+            # Create router and register routes
+            router = self.as_router()
+            
+            # Log registered routes for debugging
+            self.log.debug("router_routes_registered")
+            for route in router.routes:
+                if hasattr(route, "path"):
+                    self.log.debug("router_route", path=route.path)
+            
+            # Include the router
+            app.include_router(router, prefix=self.route)
+            
+            # Register a catch-all route for debugging and troubleshooting
+            @app.get("/{full_path:path}")
+            @app.post("/{full_path:path}")
+            async def handle_all_routes(request: Request, full_path: str):
+                self.log.debug("request_received", path=full_path)
+                
+                # Check if the path is meant for this agent
+                if not full_path.startswith(self.route.lstrip("/")):
+                    return {"error": "Invalid route"}
+                
+                # Extract the path relative to this agent's route
+                relative_path = full_path[len(self.route.lstrip("/")):]
+                relative_path = relative_path.lstrip("/")
+                self.log.debug("relative_path_extracted", path=relative_path)
+                
+                return {"error": "Path not found"}
+            
+            # Log all app routes for debugging
+            self.log.debug("app_routes_registered")
+            for route in app.routes:
+                if hasattr(route, "path"):
+                    self.log.debug("app_route", path=route.path)
+            
+            self._app = app
+        
+        return self._app
     
     def get_prompt(self) -> Union[str, List[Dict[str, Any]]]:
         """
@@ -855,7 +1033,7 @@ class AgentBase(SWMLService):
                         return pom_data['_sections']
                     # Fall through to default if nothing worked
             except Exception as e:
-                print(f"Error rendering POM: {e}")
+                self.log.error("pom_rendering_failed", error=str(e))
                 # Fall back to raw text if POM fails
                 
         # Return raw text (either explicitly set or default)
@@ -875,11 +1053,19 @@ class AgentBase(SWMLService):
         Define the tools this agent can use
         
         Returns:
-            List of SWAIGFunction objects
+            List of SWAIGFunction objects or raw dictionaries (for data_map tools)
             
         This method can be overridden by subclasses.
         """
-        return list(self._swaig_functions.values())
+        tools = []
+        for func in self._swaig_functions.values():
+            if isinstance(func, dict):
+                # Raw dictionary from register_swaig_function (e.g., DataMap)
+                tools.append(func)
+            else:
+                # SWAIGFunction object from define_tool
+                tools.append(func)
+        return tools
     
     def on_summary(self, summary: Optional[Dict[str, Any]], raw_data: Optional[Dict[str, Any]] = None) -> None:
         """
@@ -912,7 +1098,18 @@ class AgentBase(SWMLService):
         # Get the function
         func = self._swaig_functions[name]
         
-        # Call the handler
+        # Check if this is a data_map function (raw dictionary)
+        if isinstance(func, dict):
+            # Data_map functions execute on SignalWire's server, not here
+            # This should never be called, but if it is, return an error
+            return {"response": f"Data map function '{name}' should be executed by SignalWire server, not locally"}
+        
+        # Check if this is an external webhook function
+        if hasattr(func, 'webhook_url') and func.webhook_url:
+            # External webhook functions should be called directly by SignalWire, not locally
+            return {"response": f"External webhook function '{name}' should be executed by SignalWire at {func.webhook_url}, not locally"}
+        
+        # Call the handler for regular SWAIG functions
         try:
             result = func.handler(args, raw_data)
             if result is None:
@@ -979,8 +1176,19 @@ class AgentBase(SWMLService):
                 self.log.warning("unknown_function", function=function_name)
                 return False
                 
+            # Get the function and check if it's secure
+            func = self._swaig_functions[function_name]
+            is_secure = True  # Default to secure
+            
+            if isinstance(func, dict):
+                # For raw dictionaries (DataMap functions), they're always secure
+                is_secure = True
+            else:
+                # For SWAIGFunction objects, check the secure attribute
+                is_secure = func.secure
+                
             # Always allow non-secure functions
-            if not self._swaig_functions[function_name].secure:
+            if not is_secure:
                 self.log.debug("non_secure_function_allowed", function=function_name)
                 return True
             
@@ -1107,25 +1315,56 @@ class AgentBase(SWMLService):
         Returns:
             Full URL including host, port, and route (with auth if requested)
         """
-        # Start with the base URL (either proxy or local)
-        if self._proxy_url_base:
-            # Use the proxy URL base from environment, ensuring we don't duplicate the route
-            # Strip any trailing slashes from proxy base
-            proxy_base = self._proxy_url_base.rstrip('/')
-            # Make sure route starts with a slash for consistency
-            route = self.route if self.route.startswith('/') else f"/{self.route}"
-            base_url = f"{proxy_base}{route}"
+        mode = get_execution_mode()
+        
+        if mode == 'cgi':
+            protocol = 'https' if os.getenv('HTTPS') == 'on' else 'http'
+            host = os.getenv('HTTP_HOST') or os.getenv('SERVER_NAME') or 'localhost'
+            script_name = os.getenv('SCRIPT_NAME', '')
+            base_url = f"{protocol}://{host}{script_name}"
+        elif mode == 'lambda':
+            function_url = os.getenv('AWS_LAMBDA_FUNCTION_URL')
+            if function_url and ('amazonaws.com' in function_url or 'on.aws' in function_url):
+                base_url = function_url.rstrip('/')
+            else:
+                api_id = os.getenv('AWS_API_GATEWAY_ID')
+                if api_id:
+                    region = os.getenv('AWS_REGION', 'us-east-1')
+                    stage = os.getenv('AWS_API_GATEWAY_STAGE', 'prod')
+                    base_url = f"https://{api_id}.execute-api.{region}.amazonaws.com/{stage}"
+                else:
+                    import logging
+                    logging.warning("Lambda mode detected but no URL configuration found")
+                    base_url = "https://lambda-url-not-configured"
+        elif mode == 'cloud_function':
+            function_url = os.getenv('FUNCTION_URL')
+            if function_url:
+                base_url = function_url
+            else:
+                project = os.getenv('GOOGLE_CLOUD_PROJECT')
+                if project:
+                    region = os.getenv('GOOGLE_CLOUD_REGION', 'us-central1')
+                    service = os.getenv('K_SERVICE', 'function')
+                    base_url = f"https://{region}-{project}.cloudfunctions.net/{service}"
+                else:
+                    import logging
+                    logging.warning("Cloud Function mode detected but no URL configuration found")
+                    base_url = "https://cloud-function-url-not-configured"
         else:
-            # Default local URL
-            if self.host in ("0.0.0.0", "127.0.0.1", "localhost"):
-                host = "localhost"
+            # Server mode - preserve existing logic
+            if self._proxy_url_base:
+                proxy_base = self._proxy_url_base.rstrip('/')
+                route = self.route if self.route.startswith('/') else f"/{self.route}"
+                base_url = f"{proxy_base}{route}"
             else:
-                host = self.host
-                
-            base_url = f"http://{host}:{self.port}{self.route}"
+                if self.host in ("0.0.0.0", "127.0.0.1", "localhost"):
+                    host = "localhost"
+                else:
+                    host = self.host
+                base_url = f"http://{host}:{self.port}{self.route}"
             
-        # Add auth if requested
-        if include_auth:
+        # Add auth if requested (only for server mode)
+        if include_auth and mode == 'server':
             username, password = self._basic_auth
             url = urlparse(base_url)
             return url._replace(netloc=f"{username}:{password}@{url.netloc}").geturl()
@@ -1143,6 +1382,34 @@ class AgentBase(SWMLService):
         Returns:
             Fully constructed webhook URL
         """
+        # Check for serverless environment and use appropriate URL generation
+        mode = get_execution_mode()
+        
+        if mode != 'server':
+            # In serverless mode, use the serverless-appropriate URL
+            base_url = self.get_full_url()
+            
+            # For serverless, we don't need auth in webhook URLs since auth is handled differently
+            # and we want to return the actual platform URL
+            
+            # Ensure the endpoint has a trailing slash to prevent redirects
+            if endpoint in ["swaig", "post_prompt"]:
+                endpoint = f"{endpoint}/"
+                
+            # Build the full webhook URL
+            url = f"{base_url}/{endpoint}"
+            
+            # Add query parameters if any (only if they have values)
+            if query_params:
+                # Remove any call_id from query params
+                filtered_params = {k: v for k, v in query_params.items() if k != "call_id" and v}
+                if filtered_params:
+                    params = "&".join([f"{k}={v}" for k, v in filtered_params.items()])
+                    url = f"{url}?{params}"
+            
+            return url
+        
+        # Server mode - use existing logic with proxy/auth support
         # Use the parent class's implementation if available and has the same method
         if hasattr(super(), '_build_webhook_url'):
             # Ensure _proxy_url_base is synchronized
@@ -1152,7 +1419,7 @@ class AgentBase(SWMLService):
             # Call parent's implementation
             return super()._build_webhook_url(endpoint, query_params)
             
-        # Otherwise, fall back to our own implementation
+        # Otherwise, fall back to our own implementation for server mode
         # Base URL construction
         if hasattr(self, '_proxy_url_base') and self._proxy_url_base:
             # For proxy URLs
@@ -1251,33 +1518,46 @@ class AgentBase(SWMLService):
         
         # Add each function to the functions array
         for name, func in self._swaig_functions.items():
-            # Get token for secure functions when we have a call_id
-            token = None
-            if func.secure and call_id:
-                token = self._create_tool_token(tool_name=name, call_id=call_id)
-                
-            # Prepare function entry
-            function_entry = {
-                "function": name,
-                "description": func.description,
-                "parameters": {
-                    "type": "object",
-                    "properties": func.parameters
+            if isinstance(func, dict):
+                # For raw dictionaries (DataMap functions), use the entire dictionary as-is
+                # This preserves data_map and any other special fields
+                function_entry = func.copy()
+                
+                # Ensure the function name is set correctly
+                function_entry["function"] = name
+                
+            else:
+                # For SWAIGFunction objects, build the entry manually
+                # Check if it's secure and get token for secure functions when we have a call_id
+                token = None
+                if func.secure and call_id:
+                    token = self._create_tool_token(tool_name=name, call_id=call_id)
+                    
+                # Prepare function entry
+                function_entry = {
+                    "function": name,
+                    "description": func.description,
+                    "parameters": {
+                        "type": "object",
+                        "properties": func.parameters
+                    }
                 }
-            }
-            
-            # Add fillers if present
-            if func.fillers:
-                function_entry["fillers"] = func.fillers
                 
-            # Add token to URL if we have one
-            if token:
-                # Create token params without call_id
-                token_params = {"token": token}
-                function_entry["web_hook_url"] = self._build_webhook_url("swaig", token_params)
+                # Add fillers if present
+                if func.fillers:
+                    function_entry["fillers"] = func.fillers
                 
-            functions.append(function_entry)
+                # Handle webhook URL
+                if hasattr(func, 'webhook_url') and func.webhook_url:
+                    # External webhook function - use the provided URL directly
+                    function_entry["web_hook_url"] = func.webhook_url
+                elif token:
+                    # Local function with token - build local webhook URL
+                    token_params = {"token": token}
+                    function_entry["web_hook_url"] = self._build_webhook_url("swaig", token_params)
             
+            functions.append(function_entry)
+        
         # Add functions array to SWAIG object if we have any
         if functions:
             swaig_obj["functions"] = functions
@@ -1312,14 +1592,29 @@ class AgentBase(SWMLService):
         ai_handler = self.verb_registry.get_handler("ai")
         if ai_handler:
             try:
-                # Build AI config using the proper handler
-                ai_config = ai_handler.build_config(
-                    prompt_text=None if prompt_is_pom else prompt,
-                    prompt_pom=prompt if prompt_is_pom else None,
-                    post_prompt=post_prompt,
-                    post_prompt_url=post_prompt_url,
-                    swaig=swaig_obj if swaig_obj else None
-                )
+                # Check if we're in contexts mode
+                if self._contexts_defined and self._contexts_builder:
+                    # Generate contexts instead of prompt
+                    contexts_dict = self._contexts_builder.to_dict()
+                    
+                    # Build AI config with contexts
+                    ai_config = ai_handler.build_config(
+                        prompt_text=None,
+                        prompt_pom=None,
+                        contexts=contexts_dict,
+                        post_prompt=post_prompt,
+                        post_prompt_url=post_prompt_url,
+                        swaig=swaig_obj if swaig_obj else None
+                    )
+                else:
+                    # Build AI config using the traditional prompt approach
+                    ai_config = ai_handler.build_config(
+                        prompt_text=None if prompt_is_pom else prompt,
+                        prompt_pom=prompt if prompt_is_pom else None,
+                        post_prompt=post_prompt,
+                        post_prompt_url=post_prompt_url,
+                        swaig=swaig_obj if swaig_obj else None
+                    )
                 
                 # Add new configuration parameters to the AI config
                 
@@ -1345,7 +1640,7 @@ class AgentBase(SWMLService):
                     
             except ValueError as e:
                 if not self._suppress_logs:
-                    print(f"Error building AI verb configuration: {str(e)}")
+                    self.log.error("ai_verb_config_error", error=str(e))
         else:
             # Fallback if no handler (shouldn't happen but just in case)
             ai_config = {
@@ -1438,9 +1733,9 @@ class AgentBase(SWMLService):
         self._register_routes(router)
         
         # Log all registered routes for debugging
-        print(f"Registered routes for {self.name}:")
+        self.log.debug("routes_registered", agent=self.name)
         for route in router.routes:
-            print(f"  {route.path}")
+            self.log.debug("route_registered", path=route.path)
         
         return router
 
@@ -1458,6 +1753,40 @@ class AgentBase(SWMLService):
             # Create a FastAPI app with explicit redirect_slashes=False
             app = FastAPI(redirect_slashes=False)
             
+            # Add health and ready endpoints directly to the main app to avoid conflicts with catch-all
+            @app.get("/health")
+            @app.post("/health")
+            async def health_check():
+                """Health check endpoint for Kubernetes liveness probe"""
+                return {
+                    "status": "healthy",
+                    "agent": self.get_name(),
+                    "route": self.route,
+                    "functions": len(self._swaig_functions)
+                }
+            
+            @app.get("/ready")
+            @app.post("/ready")
+            async def readiness_check():
+                """Readiness check endpoint for Kubernetes readiness probe"""
+                # Check if agent is properly initialized
+                ready = (
+                    hasattr(self, '_swaig_functions') and
+                    hasattr(self, 'schema_utils') and
+                    self.schema_utils is not None
+                )
+                
+                status_code = 200 if ready else 503
+                return Response(
+                    content=json.dumps({
+                        "status": "ready" if ready else "not_ready",
+                        "agent": self.get_name(),
+                        "initialized": ready
+                    }),
+                    status_code=status_code,
+                    media_type="application/json"
+                )
+            
             # Get router for this agent
             router = self.as_router()
             
@@ -1465,7 +1794,7 @@ class AgentBase(SWMLService):
             @app.get("/{full_path:path}")
             @app.post("/{full_path:path}")
             async def handle_all_routes(request: Request, full_path: str):
-                print(f"Received request for path: {full_path}")
+                self.log.debug("request_received", path=full_path)
                 
                 # Check if the path is meant for this agent
                 if not full_path.startswith(self.route.lstrip("/")):
@@ -1474,7 +1803,7 @@ class AgentBase(SWMLService):
                 # Extract the path relative to this agent's route
                 relative_path = full_path[len(self.route.lstrip("/")):]
                 relative_path = relative_path.lstrip("/")
-                print(f"Relative path: {relative_path}")
+                self.log.debug("path_extracted", relative_path=relative_path)
                 
                 # Perform routing based on the relative path
                 if not relative_path or relative_path == "/":
@@ -1509,11 +1838,11 @@ class AgentBase(SWMLService):
             # Include router with prefix
             app.include_router(router, prefix=self.route)
             
-            # Print all app routes for debugging
-            print(f"All app routes:")
+            # Log all app routes for debugging
+            self.log.debug("app_routes_registered")
             for route in app.routes:
                 if hasattr(route, "path"):
-                    print(f"  {route.path}")
+                    self.log.debug("app_route", path=route.path)
             
             self._app = app
         
@@ -1522,12 +1851,290 @@ class AgentBase(SWMLService):
         
         # Print the auth credentials with source
         username, password, source = self.get_basic_auth_credentials(include_source=True)
+        
+        # Log startup information using structured logging
+        self.log.info("agent_starting",
+                     agent=self.name,
+                     url=f"http://{host}:{port}{self.route}",
+                     username=username,
+                     password_length=len(password),
+                     auth_source=source)
+        
+        # Print user-friendly startup message (keep this for development UX)
         print(f"Agent '{self.name}' is available at:")
         print(f"URL: http://{host}:{port}{self.route}")
         print(f"Basic Auth: {username}:{password} (source: {source})")
         
         uvicorn.run(self._app, host=host, port=port)
 
+    def run(self, event=None, context=None, force_mode=None, host: Optional[str] = None, port: Optional[int] = None):
+        """
+        Smart run method that automatically detects environment and handles accordingly
+        
+        Args:
+            event: Serverless event object (Lambda, Cloud Functions)
+            context: Serverless context object (Lambda, Cloud Functions)
+            force_mode: Override automatic mode detection for testing
+            host: Host override for server mode
+            port: Port override for server mode
+            
+        Returns:
+            Response for serverless modes, None for server mode
+        """
+        mode = force_mode or get_execution_mode()
+        
+        try:
+            if mode in ['cgi', 'cloud_function', 'azure_function']:
+                response = self.handle_serverless_request(event, context, mode)
+                print(response)
+                return response
+            elif mode == 'lambda':
+                return self.handle_serverless_request(event, context, mode)
+            else:
+                # Server mode - use existing serve method
+                self.serve(host, port)
+        except Exception as e:
+            import logging
+            logging.error(f"Error in run method: {e}")
+            if mode == 'lambda':
+                return {
+                    "statusCode": 500,
+                    "headers": {"Content-Type": "application/json"},
+                    "body": json.dumps({"error": str(e)})
+                }
+            else:
+                raise
+
+    def handle_serverless_request(self, event=None, context=None, mode=None):
+        """
+        Handle serverless environment requests (CGI, Lambda, Cloud Functions)
+        
+        Args:
+            event: Serverless event object (Lambda, Cloud Functions)
+            context: Serverless context object (Lambda, Cloud Functions)
+            mode: Override execution mode (from force_mode in run())
+            
+        Returns:
+            Response appropriate for the serverless platform
+        """
+        if mode is None:
+            mode = get_execution_mode()
+        
+        try:
+            if mode == 'cgi':
+                path_info = os.getenv('PATH_INFO', '').strip('/')
+                if not path_info:
+                    return self._render_swml()
+                else:
+                    # Parse CGI request for SWAIG function call
+                    args = {}
+                    call_id = None
+                    raw_data = None
+                    
+                    # Try to parse POST data from stdin for CGI
+                    import sys
+                    content_length = os.getenv('CONTENT_LENGTH')
+                    if content_length and content_length.isdigit():
+                        try:
+                            post_data = sys.stdin.read(int(content_length))
+                            if post_data:
+                                raw_data = json.loads(post_data)
+                                call_id = raw_data.get("call_id")
+                                
+                                # Extract arguments like the FastAPI handler does
+                                if "argument" in raw_data and isinstance(raw_data["argument"], dict):
+                                    if "parsed" in raw_data["argument"] and isinstance(raw_data["argument"]["parsed"], list) and raw_data["argument"]["parsed"]:
+                                        args = raw_data["argument"]["parsed"][0]
+                                    elif "raw" in raw_data["argument"]:
+                                        try:
+                                            args = json.loads(raw_data["argument"]["raw"])
+                                        except Exception:
+                                            pass
+                        except Exception:
+                            # If parsing fails, continue with empty args
+                            pass
+                    
+                    return self._execute_swaig_function(path_info, args, call_id, raw_data)
+            
+            elif mode == 'lambda':
+                if event:
+                    path = event.get('pathParameters', {}).get('proxy', '') if event.get('pathParameters') else ''
+                    if not path:
+                        swml_response = self._render_swml()
+                        return {
+                            "statusCode": 200,
+                            "headers": {"Content-Type": "application/json"},
+                            "body": swml_response
+                        }
+                    else:
+                        # Parse Lambda event for SWAIG function call
+                        args = {}
+                        call_id = None
+                        raw_data = None
+                        
+                        # Parse request body if present
+                        body_content = event.get('body')
+                        if body_content:
+                            try:
+                                if isinstance(body_content, str):
+                                    raw_data = json.loads(body_content)
+                                else:
+                                    raw_data = body_content
+                                    
+                                call_id = raw_data.get("call_id")
+                                
+                                # Extract arguments like the FastAPI handler does
+                                if "argument" in raw_data and isinstance(raw_data["argument"], dict):
+                                    if "parsed" in raw_data["argument"] and isinstance(raw_data["argument"]["parsed"], list) and raw_data["argument"]["parsed"]:
+                                        args = raw_data["argument"]["parsed"][0]
+                                    elif "raw" in raw_data["argument"]:
+                                        try:
+                                            args = json.loads(raw_data["argument"]["raw"])
+                                        except Exception:
+                                            pass
+                            except Exception:
+                                # If parsing fails, continue with empty args
+                                pass
+                        
+                        result = self._execute_swaig_function(path, args, call_id, raw_data)
+                        return {
+                            "statusCode": 200,
+                            "headers": {"Content-Type": "application/json"},
+                            "body": json.dumps(result) if isinstance(result, dict) else str(result)
+                        }
+                else:
+                    # Handle case when event is None (direct Lambda call with no event)
+                    swml_response = self._render_swml()
+                    return {
+                        "statusCode": 200,
+                        "headers": {"Content-Type": "application/json"},
+                        "body": swml_response
+                    }
+            
+            elif mode in ['cloud_function', 'azure_function']:
+                return self._handle_cloud_function_request(event)
+                
+        except Exception as e:
+            import logging
+            logging.error(f"Error in serverless request handler: {e}")
+            if mode == 'lambda':
+                return {
+                    "statusCode": 500,
+                    "headers": {"Content-Type": "application/json"},
+                    "body": json.dumps({"error": str(e)})
+                }
+            else:
+                raise
+
+    def _handle_cloud_function_request(self, request):
+        """
+        Handle Cloud Function specific requests
+        
+        Args:
+            request: Cloud Function request object
+            
+        Returns:
+            Cloud Function response
+        """
+        # Platform-specific implementation would go here
+        # For now, return basic SWML response
+        return self._render_swml()
+
+    def _execute_swaig_function(self, function_name: str, args: Optional[Dict[str, Any]] = None, call_id: Optional[str] = None, raw_data: Optional[Dict[str, Any]] = None):
+        """
+        Execute a SWAIG function in serverless context
+        
+        Args:
+            function_name: Name of the function to execute
+            args: Function arguments dictionary
+            call_id: Optional call ID
+            raw_data: Optional raw request data
+            
+        Returns:
+            Function execution result
+        """
+        import structlog
+        
+        # Use the existing logger
+        req_log = self.log.bind(
+            endpoint="serverless_swaig",
+            function=function_name
+        )
+        
+        if call_id:
+            req_log = req_log.bind(call_id=call_id)
+            
+        req_log.debug("serverless_function_call_received")
+        
+        try:
+            # Validate function exists
+            if function_name not in self._swaig_functions:
+                req_log.warning("function_not_found", available_functions=list(self._swaig_functions.keys()))
+                return {"error": f"Function '{function_name}' not found"}
+            
+            # Use empty args if not provided
+            if args is None:
+                args = {}
+                
+            # Use empty raw_data if not provided, but include function call structure
+            if raw_data is None:
+                raw_data = {
+                    "function": function_name,
+                    "argument": {
+                        "parsed": [args] if args else [],
+                        "raw": json.dumps(args) if args else "{}"
+                    }
+                }
+                if call_id:
+                    raw_data["call_id"] = call_id
+            
+            req_log.debug("executing_function", args=json.dumps(args))
+            
+            # Call the function using the existing on_function_call method
+            result = self.on_function_call(function_name, args, raw_data)
+            
+            # Convert result to dict if needed (same logic as in _handle_swaig_request)
+            if isinstance(result, SwaigFunctionResult):
+                result_dict = result.to_dict()
+            elif isinstance(result, dict):
+                result_dict = result
+            else:
+                result_dict = {"response": str(result)}
+            
+            req_log.info("serverless_function_executed_successfully")
+            req_log.debug("function_result", result=json.dumps(result_dict))
+            return result_dict
+            
+        except Exception as e:
+            req_log.error("serverless_function_execution_error", error=str(e))
+            return {"error": str(e), "function": function_name}
+
+    def setup_graceful_shutdown(self) -> None:
+        """
+        Setup signal handlers for graceful shutdown (useful for Kubernetes)
+        """
+        def signal_handler(signum, frame):
+            self.log.info("shutdown_signal_received", signal=signum)
+            
+            # Perform cleanup
+            try:
+                # Close any open resources
+                if hasattr(self, '_session_manager'):
+                    # Could add cleanup logic here
+                    pass
+                
+                self.log.info("cleanup_completed")
+            except Exception as e:
+                self.log.error("cleanup_error", error=str(e))
+            finally:
+                sys.exit(0)
+        
+        # Register handlers for common termination signals
+        signal.signal(signal.SIGTERM, signal_handler)  # Kubernetes sends this
+        signal.signal(signal.SIGINT, signal_handler)   # Ctrl+C
+        
+        self.log.debug("graceful_shutdown_handlers_registered")
+
     def on_swml_request(self, request_data: Optional[dict] = None, callback_path: Optional[str] = None) -> Optional[dict]:
         """
         Customization point for subclasses to modify SWML based on request data
@@ -1552,6 +2159,8 @@ class AgentBase(SWMLService):
         Args:
             router: FastAPI router to register routes with
         """
+        # Health check endpoints are now registered directly on the main app
+        
         # Root endpoint (handles both with and without trailing slash)
         @router.get("/")
         @router.post("/")