signalwire-agents 0.1.27__py3-none-any.whl → 0.1.28__py3-none-any.whl

signalwire_agents/__init__.py

@@ -18,13 +18,12 @@ A package for building AI agents using SignalWire's AI and SWML capabilities.
 from .core.logging_config import configure_logging
 configure_logging()
 
-__version__ = "0.1.27"
+__version__ = "0.1.28"
 
 # Import core classes for easier access
 from .core.agent_base import AgentBase
 from .core.contexts import ContextBuilder, Context, Step, create_simple_context
 from .core.data_map import DataMap, create_simple_api_tool, create_expression_tool
-from .core.state import StateManager, FileStateManager
 from signalwire_agents.agent_server import AgentServer
 from signalwire_agents.core.swml_service import SWMLService
 from signalwire_agents.core.swml_builder import SWMLBuilder
@@ -68,8 +67,6 @@ __all__ = [
     "AgentServer", 
     "SWMLService",
     "SWMLBuilder",
-    "StateManager",
-    "FileStateManager",
     "SwaigFunctionResult",
     "SWAIGFunction",
     "DataMap",

signalwire_agents/cli/config.py

@@ -41,12 +41,22 @@ ERROR_FUNCTION_NOT_FOUND = "Function '{function_name}' not found in agent"
 ERROR_CGI_HOST_REQUIRED = "CGI simulation requires --cgi-host"
 
 # Help messages
-HELP_DESCRIPTION = "Test SWAIG functions and generate SWML documents for SignalWire AI agents"
+HELP_DESCRIPTION = """Test SWAIG functions and generate SWML documents for SignalWire AI agents
+
+IMPORTANT: When using --exec, ALL options (like --call-id, --verbose, etc.) must come BEFORE --exec.
+Everything after --exec <function_name> is treated as arguments to the function."""
+
 HELP_EPILOG_SHORT = """
 examples:
   # Execute a function
   %(prog)s agent.py --exec search --query "test" --limit 5
   
+  # Execute with persistent session (--call-id MUST come BEFORE --exec)
+  %(prog)s agent.py --call-id my-session --exec add_todo --text "Buy milk"
+  
+  # WRONG: This won't work! --call-id is treated as a function argument
+  %(prog)s agent.py --exec add_todo --text "Buy milk" --call-id my-session
+  
   # Generate SWML
   %(prog)s agent.py --dump-swml --raw | jq '.'
   

signalwire_agents/cli/simulation/data_overrides.py

@@ -120,8 +120,12 @@ def apply_convenience_mappings(data: Dict[str, Any], args: argparse.Namespace) -
     
     # Map high-level arguments to specific paths
     if hasattr(args, 'call_id') and args.call_id:
-        set_nested_value(data, "call.call_id", args.call_id)
-        set_nested_value(data, "call.tag", args.call_id)  # tag often matches call_id
+        # Set at root level for SWAIG functions
+        data["call_id"] = args.call_id
+        # Also set in call object if it exists
+        if "call" in data:
+            set_nested_value(data, "call.call_id", args.call_id)
+            set_nested_value(data, "call.tag", args.call_id)  # tag often matches call_id
     
     if hasattr(args, 'project_id') and args.project_id:
         set_nested_value(data, "call.project_id", args.project_id)

signalwire_agents/cli/test_swaig.py

@@ -727,6 +727,12 @@ def main():
                     # Default behavior - minimal data
                     post_data = generate_minimal_post_data(args.tool_name, function_args)
                 
+                # Apply convenience mappings from CLI args (e.g., --call-id)
+                post_data = apply_convenience_mappings(post_data, args)
+                
+                # Apply explicit overrides
+                post_data = apply_overrides(post_data, args.override, args.override_json)
+                
                 if args.verbose:
                     print(f"Post data: {json.dumps(post_data, indent=2)}")
                     print("-" * 60)

signalwire_agents/core/agent_base.py

@@ -49,7 +49,6 @@ from signalwire_agents.core.swaig_function import SWAIGFunction
 from signalwire_agents.core.function_result import SwaigFunctionResult
 from signalwire_agents.core.swml_renderer import SwmlRenderer
 from signalwire_agents.core.security.session_manager import SessionManager
-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
@@ -113,13 +112,11 @@ class AgentBase(
         port: int = 3000,
         basic_auth: Optional[Tuple[str, str]] = None,
         use_pom: bool = True,
-        enable_state_tracking: bool = False,
         token_expiry_secs: int = 3600,
         auto_answer: bool = True,
         record_call: bool = False,
         record_format: str = "mp4",
         record_stereo: bool = True,
-        state_manager: Optional[StateManager] = None,
         default_webhook_url: Optional[str] = None,
         agent_id: Optional[str] = None,
         native_functions: Optional[List[str]] = None,
@@ -138,13 +135,11 @@ class AgentBase(
             port: Port to bind the web server to
             basic_auth: Optional (username, password) tuple for basic auth
             use_pom: Whether to use POM for prompt building
-            enable_state_tracking: Whether to register startup_hook and hangup_hook SWAIG functions to track conversation state
             token_expiry_secs: Seconds until tokens expire
             auto_answer: Whether to automatically answer calls
             record_call: Whether to record calls
             record_format: Recording format
             record_stereo: Whether to record in stereo
-            state_manager: Optional state manager for this agent
             default_webhook_url: Optional default webhook URL for all SWAIG functions
             agent_id: Optional unique ID for this agent, generated if not provided
             native_functions: Optional list of native functions to include in the SWAIG object
@@ -207,7 +202,6 @@ class AgentBase(
         
         # Initialize session manager
         self._session_manager = SessionManager(token_expiry_secs=token_expiry_secs)
-        self._enable_state_tracking = enable_state_tracking
         
         # URL override variables
         self._web_hook_url_override = None
@@ -229,8 +223,6 @@ class AgentBase(
         # Process declarative PROMPT_SECTIONS if defined in subclass
         self._process_prompt_sections()
         
-        # Initialize state manager
-        self._state_manager = state_manager or FileStateManager()
         
         # Process class-decorated tools (using @AgentBase.tool)
         self._tool_registry.register_class_decorated_tools()
@@ -238,9 +230,6 @@ class AgentBase(
         # Add native_functions parameter
         self.native_functions = native_functions or []
         
-        # Register state tracking tools if enabled
-        if enable_state_tracking:
-            self._register_state_tracking_tools()
         
         # Initialize new configuration containers
         self._hints = []
@@ -581,7 +570,7 @@ class AgentBase(
         post_prompt = agent_to_use.get_post_prompt()
         
         # Generate a call ID if needed
-        if agent_to_use._enable_state_tracking and call_id is None:
+        if call_id is None:
             call_id = agent_to_use._session_manager.create_session()
             
         # Start with any SWAIG query params that were set

signalwire_agents/core/mixins/state_mixin.py

@@ -150,70 +150,4 @@ class StateMixin:
             self.log.error("token_validation_error", error=str(e), function=function_name)
             return False
     
-    # Note: set_dynamic_config_callback is implemented in WebMixin
-    
-    def _register_state_tracking_tools(self):
-        """
-        Register special tools for state tracking
-        
-        This adds startup_hook and hangup_hook SWAIG functions that automatically
-        activate and deactivate the session when called. These are useful for
-        tracking call state and cleaning up resources when a call ends.
-        """
-        # Register startup hook to activate session
-        self.define_tool(
-            name="startup_hook",
-            description="Called when a new conversation starts to initialize state",
-            parameters={},
-            handler=lambda args, raw_data: self._handle_startup_hook(args, raw_data),
-            secure=False  # No auth needed for this system function
-        )
-        
-        # Register hangup hook to end session
-        self.define_tool(
-            name="hangup_hook",
-            description="Called when conversation ends to clean up resources",
-            parameters={},
-            handler=lambda args, raw_data: self._handle_hangup_hook(args, raw_data),
-            secure=False  # No auth needed for this system function
-        )
-    
-    def _handle_startup_hook(self, args, raw_data):
-        """
-        Handle the startup hook function call
-        
-        Args:
-            args: Function arguments (empty for this hook)
-            raw_data: Raw request data containing call_id
-            
-        Returns:
-            Success response
-        """
-        call_id = raw_data.get("call_id") if raw_data else None
-        if call_id:
-            self.log.info("session_activated", call_id=call_id)
-            self._session_manager.activate_session(call_id)
-            return SwaigFunctionResult("Session activated")
-        else:
-            self.log.warning("session_activation_failed", error="No call_id provided")
-            return SwaigFunctionResult("Failed to activate session: No call_id provided")
-    
-    def _handle_hangup_hook(self, args, raw_data):
-        """
-        Handle the hangup hook function call
-        
-        Args:
-            args: Function arguments (empty for this hook)
-            raw_data: Raw request data containing call_id
-            
-        Returns:
-            Success response
-        """
-        call_id = raw_data.get("call_id") if raw_data else None
-        if call_id:
-            self.log.info("session_ended", call_id=call_id)
-            self._session_manager.end_session(call_id)
-            return SwaigFunctionResult("Session ended")
-        else:
-            self.log.warning("session_end_failed", error="No call_id provided")
-            return SwaigFunctionResult("Failed to end session: No call_id provided")
+    # Note: set_dynamic_config_callback is implemented in WebMixin

signalwire_agents/core/mixins/tool_mixin.py

@@ -161,71 +161,6 @@ class ToolMixin:
             # If the handler raises an exception, return an error response
             return {"response": f"Error executing function '{name}': {str(e)}"}
     
-    def _register_state_tracking_tools(self):
-        """
-        Register special tools for state tracking
-        
-        This adds startup_hook and hangup_hook SWAIG functions that automatically
-        activate and deactivate the session when called. These are useful for
-        tracking call state and cleaning up resources when a call ends.
-        """
-        # Register startup hook to activate session
-        self.define_tool(
-            name="startup_hook",
-            description="Called when a new conversation starts to initialize state",
-            parameters={},
-            handler=lambda args, raw_data: self._handle_startup_hook(args, raw_data),
-            secure=False  # No auth needed for this system function
-        )
-        
-        # Register hangup hook to end session
-        self.define_tool(
-            name="hangup_hook",
-            description="Called when conversation ends to clean up resources",
-            parameters={},
-            handler=lambda args, raw_data: self._handle_hangup_hook(args, raw_data),
-            secure=False  # No auth needed for this system function
-        )
-    
-    def _handle_startup_hook(self, args, raw_data):
-        """
-        Handle the startup hook function call
-        
-        Args:
-            args: Function arguments (empty for this hook)
-            raw_data: Raw request data containing call_id
-            
-        Returns:
-            Success response
-        """
-        call_id = raw_data.get("call_id") if raw_data else None
-        if call_id:
-            self.log.info("session_activated", call_id=call_id)
-            self._session_manager.activate_session(call_id)
-            return SwaigFunctionResult("Session activated")
-        else:
-            self.log.warning("session_activation_failed", error="No call_id provided")
-            return SwaigFunctionResult("Failed to activate session: No call_id provided")
-    
-    def _handle_hangup_hook(self, args, raw_data):
-        """
-        Handle the hangup hook function call
-        
-        Args:
-            args: Function arguments (empty for this hook)
-            raw_data: Raw request data containing call_id
-            
-        Returns:
-            Success response
-        """
-        call_id = raw_data.get("call_id") if raw_data else None
-        if call_id:
-            self.log.info("session_ended", call_id=call_id)
-            self._session_manager.end_session(call_id)
-            return SwaigFunctionResult("Session ended")
-        else:
-            self.log.warning("session_end_failed", error="No call_id provided")
-            return SwaigFunctionResult("Failed to end session: No call_id provided")
     
     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):
         """

signalwire_agents/prefabs/concierge.py

@@ -52,7 +52,6 @@ class ConciergeAgent(AgentBase):
         welcome_message: Optional[str] = None,
         name: str = "concierge",
         route: str = "/concierge",
-        enable_state_tracking: bool = True,
         **kwargs
     ):
         """
@@ -67,7 +66,6 @@ class ConciergeAgent(AgentBase):
             welcome_message: Optional custom welcome message
             name: Agent name for the route
             route: HTTP route for this agent
-            enable_state_tracking: Whether to enable state tracking (default: True)
             **kwargs: Additional arguments for AgentBase
         """
         # Initialize the base agent
@@ -75,7 +73,6 @@ class ConciergeAgent(AgentBase):
             name=name,
             route=route,
             use_pom=True,
-            enable_state_tracking=enable_state_tracking,
             **kwargs
         )
         

signalwire_agents/prefabs/faq_bot.py

@@ -51,7 +51,6 @@ class FAQBotAgent(AgentBase):
         persona: Optional[str] = None,
         name: str = "faq_bot",
         route: str = "/faq",
-        enable_state_tracking: bool = True,  # Enable state tracking by default
         **kwargs
     ):
         """
@@ -66,7 +65,6 @@ class FAQBotAgent(AgentBase):
             persona: Optional custom personality description
             name: Agent name for the route
             route: HTTP route for this agent
-            enable_state_tracking: Whether to enable state tracking (default: True)
             **kwargs: Additional arguments for AgentBase
         """
         # Initialize the base agent
@@ -74,7 +72,6 @@ class FAQBotAgent(AgentBase):
             name=name,
             route=route,
             use_pom=True,
-            enable_state_tracking=enable_state_tracking,  # Pass state tracking parameter to base
             **kwargs
         )
         

signalwire_agents/prefabs/info_gatherer.py

@@ -45,7 +45,6 @@ class InfoGathererAgent(AgentBase):
         questions: Optional[List[Dict[str, str]]] = None,
         name: str = "info_gatherer", 
         route: str = "/info_gatherer",
-        enable_state_tracking: bool = True,  # Enable state tracking by default for InfoGatherer
         **kwargs
     ):
         """
@@ -59,7 +58,6 @@ class InfoGathererAgent(AgentBase):
                 - confirm: (Optional) If set to True, the agent will confirm the answer before submitting
             name: Agent name for the route
             route: HTTP route for this agent
-            enable_state_tracking: Whether to enable state tracking (default: True)
             **kwargs: Additional arguments for AgentBase
         """
         # Initialize the base agent
@@ -67,7 +65,6 @@ class InfoGathererAgent(AgentBase):
             name=name,
             route=route,
             use_pom=True,
-            enable_state_tracking=enable_state_tracking,  # Pass state tracking parameter to base
             **kwargs
         )
         

signalwire_agents/prefabs/receptionist.py

@@ -41,7 +41,6 @@ class ReceptionistAgent(AgentBase):
         route: str = "/receptionist",
         greeting: str = "Thank you for calling. How can I help you today?",
         voice: str = "rime.spore",
-        enable_state_tracking: bool = True,  # Enable state tracking by default
         **kwargs
     ):
         """
@@ -56,7 +55,6 @@ class ReceptionistAgent(AgentBase):
             route: HTTP route for this agent
             greeting: Initial greeting message
             voice: Voice ID to use
-            enable_state_tracking: Whether to enable state tracking (default: True)
             **kwargs: Additional arguments for AgentBase
         """
         # Initialize the base agent
@@ -64,7 +62,6 @@ class ReceptionistAgent(AgentBase):
             name=name,
             route=route,
             use_pom=True,
-            enable_state_tracking=enable_state_tracking,  # Pass state tracking parameter to base
             **kwargs
         )
         

signalwire_agents/prefabs/survey.py

@@ -62,7 +62,6 @@ class SurveyAgent(AgentBase):
         max_retries: int = 2,
         name: str = "survey",
         route: str = "/survey",
-        enable_state_tracking: bool = True,  # Enable state tracking by default
         **kwargs
     ):
         """
@@ -83,7 +82,6 @@ class SurveyAgent(AgentBase):
             max_retries: Maximum number of times to retry invalid answers
             name: Name for the agent (default: "survey")
             route: HTTP route for the agent (default: "/survey")
-            enable_state_tracking: Whether to enable state tracking (default: True)
             **kwargs: Additional arguments for AgentBase
         """
         # Initialize the base agent
@@ -91,7 +89,6 @@ class SurveyAgent(AgentBase):
             name=name,
             route=route,
             use_pom=True,
-            enable_state_tracking=enable_state_tracking,  # Pass state tracking parameter to base
             **kwargs
         )
         

signalwire_agents/skills/mcp_gateway/README.md

@@ -0,0 +1,230 @@
+# MCP Gateway Skill
+
+Bridge MCP (Model Context Protocol) servers with SignalWire SWAIG functions, allowing agents to seamlessly interact with MCP-based tools.
+
+## Description
+
+The MCP Gateway skill connects SignalWire agents to MCP servers through a centralized gateway service. It dynamically discovers and registers MCP tools as SWAIG functions, maintaining session state throughout each call.
+
+## Features
+
+- Dynamic tool discovery from MCP servers
+- Session management tied to SignalWire call IDs
+- Automatic cleanup on call hangup
+- Support for multiple MCP services
+- Selective tool loading
+- HTTPS support with SSL verification
+- Retry logic for resilient connections
+
+## Requirements
+
+- Running MCP Gateway service
+- Network access to gateway
+- Gateway credentials (username/password)
+
+## Configuration
+
+### Required Parameters
+
+Either Basic Auth credentials OR Bearer token:
+- `gateway_url`: URL of the MCP gateway service (default: "http://localhost:8100")
+- `auth_user` + `auth_password`: Basic auth credentials
+- OR `auth_token`: Bearer token for authentication
+
+### Optional Parameters
+
+- `services`: Array of services to load (default: all available)
+  - `name`: Service name
+  - `tools`: Array of tool names or "*" for all (default: all)
+- `session_timeout`: Session timeout in seconds (default: 300)
+- `tool_prefix`: Prefix for SWAIG function names (default: "mcp_")
+- `retry_attempts`: Number of retry attempts (default: 3)
+- `request_timeout`: HTTP request timeout in seconds (default: 30)
+- `verify_ssl`: Verify SSL certificates (default: true)
+
+## Usage
+
+### Basic Usage (All Services)
+
+```python
+from signalwire_agents import AgentBase
+
+class MyAgent(AgentBase):
+    def __init__(self):
+        super().__init__(name="My Agent")
+        
+        # Load all available MCP services
+        self.add_skill("mcp_gateway", {
+            "gateway_url": "http://localhost:8080",
+            "auth_user": "admin",
+            "auth_password": "changeme"
+        })
+
+agent = MyAgent()
+agent.run()
+```
+
+### Selective Service Loading
+
+```python
+# Load specific services with specific tools
+self.add_skill("mcp_gateway", {
+    "gateway_url": "https://gateway.example.com",
+    "auth_user": "admin",
+    "auth_password": "secret",
+    "services": [
+        {
+            "name": "todo",
+            "tools": ["add_todo", "list_todos"]  # Only these tools
+        },
+        {
+            "name": "calculator",
+            "tools": "*"  # All calculator tools
+        }
+    ],
+    "session_timeout": 600,
+    "tool_prefix": "ext_"
+})
+```
+
+### HTTPS with Self-Signed Certificate
+
+```python
+self.add_skill("mcp_gateway", {
+    "gateway_url": "https://localhost:8443",
+    "auth_user": "admin",
+    "auth_password": "secret",
+    "verify_ssl": False  # For self-signed certificates
+})
+```
+
+### Bearer Token Authentication
+
+```python
+self.add_skill("mcp_gateway", {
+    "gateway_url": "https://gateway.example.com",
+    "auth_token": "your-bearer-token-here",
+    "services": [{
+        "name": "todo"
+    }]
+})
+```
+
+## Generated Functions
+
+The skill dynamically generates SWAIG functions based on discovered MCP tools. Function names follow the pattern:
+
+`{tool_prefix}{service_name}_{tool_name}`
+
+For example, with default settings:
+- `mcp_todo_add_todo` - Add a todo item
+- `mcp_todo_list_todos` - List todo items
+- `mcp_calculator_add` - Calculator addition
+
+## Example Conversations
+
+### Using Todo Service
+
+```
+User: "Add a task to buy milk"
+Assistant: "I'll add that to your todo list."
+[Calls mcp_todo_add_todo with text="buy milk"]
+Assistant: "I've added 'buy milk' to your todo list."
+
+User: "What's on my todo list?"
+Assistant: "Let me check your todos."
+[Calls mcp_todo_list_todos]
+Assistant: "Here are your current todos:
+○ #1 [medium] buy milk"
+```
+
+### Multiple Services
+
+```
+User: "Add 'finish report' to my todos and calculate 15% of 200"
+Assistant: "I'll add that todo and do the calculation for you."
+[Calls mcp_todo_add_todo with text="finish report"]
+[Calls mcp_calculator_percent with value=200, percent=15]
+Assistant: "I've added 'finish report' to your todos. 15% of 200 is 30."
+```
+
+## Session Management
+
+- Each SignalWire call gets its own MCP session
+- Sessions persist across multiple tool calls
+- Automatic cleanup on call hangup
+- Configurable timeout for inactive sessions
+
+### Custom Session ID
+
+You can override the session ID by setting `mcp_call_id` in global_data:
+
+```python
+# In your agent code
+self.set_global_data({
+    "mcp_call_id": "custom-session-123"
+})
+
+# Or in a SWAIG function
+result = SwaigFunctionResult("Session changed")
+result.add_action("set_global_data", {"mcp_call_id": "new-session-456"})
+```
+
+This is useful for:
+- Managing multiple MCP sessions within a single call
+- Sharing MCP sessions across different calls
+- Custom session management strategies
+
+## Troubleshooting
+
+### Gateway Connection Failed
+
+Check:
+1. Gateway service is running
+2. Correct URL and credentials
+3. Network connectivity
+4. Firewall rules
+
+### SSL Certificate Errors
+
+For self-signed certificates:
+```python
+"verify_ssl": False
+```
+
+For custom CA certificates, ensure they're in the system trust store.
+
+### Tool Not Found
+
+Verify:
+1. Service name is correct
+2. Tool name matches exactly
+3. Tool is included in service configuration
+4. MCP server is returning tools correctly
+
+### Session Timeouts
+
+Increase timeout if needed:
+```python
+"session_timeout": 600  # 10 minutes
+```
+
+## Gateway Setup
+
+To run the MCP Gateway service:
+
+```bash
+cd mcp_gateway
+python3 gateway_service.py
+
+# Or with custom config
+python3 gateway_service.py -c myconfig.json
+```
+
+## Security Considerations
+
+1. Always use HTTPS in production
+2. Use strong authentication credentials
+3. Limit service access to required tools only
+4. Monitor gateway logs for suspicious activity
+5. Set appropriate session timeouts

signalwire_agents/skills/mcp_gateway/__init__.py

@@ -0,0 +1 @@
+"""MCP Gateway Skill for SignalWire Agents"""