signalwire-agents 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

signalwire_agents/prefabs/info_gatherer.py

@@ -0,0 +1,263 @@
+"""
+Copyright (c) 2025 SignalWire
+
+This file is part of the SignalWire AI Agents SDK.
+
+Licensed under the MIT License.
+See LICENSE file in the project root for full license information.
+"""
+
+"""
+InfoGathererAgent - Prefab agent for collecting answers to a series of questions
+"""
+
+from typing import List, Dict, Any, Optional, Union
+import json
+
+from signalwire_agents.core.agent_base import AgentBase
+from signalwire_agents.core.function_result import SwaigFunctionResult
+
+
+class InfoGathererAgent(AgentBase):
+    """
+    A prefab agent designed to collect answers to a series of questions.
+    
+    This agent will:
+    1. Ask if the user is ready to begin
+    2. Ask each question in sequence
+    3. Store the answers for later use
+    
+    Example:
+        agent = InfoGathererAgent(
+            questions=[
+                {"key_name": "full_name", "question_text": "What is your full name?"},
+                {"key_name": "email", "question_text": "What is your email address?", "confirm": True},
+                {"key_name": "reason", "question_text": "How can I help you today?"}
+            ]
+        )
+    """
+    
+    def __init__(
+        self,
+        questions: List[Dict[str, str]],
+        name: str = "info_gatherer", 
+        route: str = "/info_gatherer",
+        **kwargs
+    ):
+        """
+        Initialize an information gathering agent
+        
+        Args:
+            questions: List of questions to ask, each with:
+                - key_name: Identifier for storing the answer
+                - question_text: The actual question to ask the user
+                - 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
+            **kwargs: Additional arguments for AgentBase
+        """
+        # Initialize the base agent
+        super().__init__(
+            name=name,
+            route=route,
+            use_pom=True,
+            **kwargs
+        )
+        
+        # Validate questions format
+        self._validate_questions(questions)
+        
+        # Set up global data with questions and initial state
+        self.set_global_data({
+            "questions": questions,
+            "question_index": 0,
+            "answers": []
+        })
+        
+        # Build a minimal prompt
+        self._build_prompt()
+        
+        # Configure additional agent settings
+        self._configure_agent_settings()
+    
+    def _validate_questions(self, questions):
+        """Validate that questions are in the correct format"""
+        if not questions:
+            raise ValueError("At least one question is required")
+            
+        for i, question in enumerate(questions):
+            if "key_name" not in question:
+                raise ValueError(f"Question {i+1} is missing 'key_name' field")
+            if "question_text" not in question:
+                raise ValueError(f"Question {i+1} is missing 'question_text' field")
+    
+    def _build_prompt(self):
+        """Build a minimal prompt with just the objective"""
+        self.prompt_add_section(
+            "Objective", 
+            body="Your role is to get answers to a series of questions. Begin by asking the user if they are ready to answer some questions. If they confirm they are ready, call the start_questions function to begin the process."
+        )
+    
+    def _configure_agent_settings(self):
+        """Configure additional agent settings"""
+        # Set AI behavior parameters
+        self.set_params({
+            "end_of_speech_timeout": 800,
+            "speech_event_timeout": 1000  # Slightly longer for thoughtful responses
+        })
+    
+    def _generate_question_instruction(self, question_text: str, needs_confirmation: bool, is_first_question: bool = False) -> str:
+        """
+        Generate the instruction text for asking a question
+        
+        Args:
+            question_text: The question to ask
+            needs_confirmation: Whether confirmation is required
+            is_first_question: Whether this is the first question or a subsequent one
+            
+        Returns:
+            Formatted instruction text
+        """
+        # Start with the appropriate prefix based on whether this is the first question
+        if is_first_question:
+            instruction = f"Ask the user to answer the following question: {question_text}\n\n"
+        else:
+            instruction = f"Previous Answer recorded. Now ask the user to answer the following question: {question_text}\n\n"
+        
+        # Add the common part
+        instruction += "Make sure the answer fits the scope and context of the question before submitting it. "
+        
+        # Add confirmation guidance if needed
+        if needs_confirmation:
+            instruction += "Insist that the user confirms the answer as many times as needed until they say it is correct."
+        else:
+            instruction += "You don't need the user to confirm the answer to this question."
+            
+        return instruction
+    
+    @AgentBase.tool(
+        name="start_questions",
+        description="Start the question sequence with the first question",
+        parameters={}
+    )
+    def start_questions(self, args, raw_data):
+        """
+        Start the question sequence by retrieving the first question
+        
+        This function gets the current question index from global_data
+        and returns the corresponding question.
+        """
+        # Get global data
+        global_data = raw_data.get("global_data", {})
+        questions = global_data.get("questions", [])
+        question_index = global_data.get("question_index", 0)
+        
+        # Check if we have questions
+        if not questions or question_index >= len(questions):
+            return SwaigFunctionResult("I don't have any questions to ask.")
+        
+        # Get the current question
+        current_question = questions[question_index]
+        question_text = current_question.get("question_text", "")
+        needs_confirmation = current_question.get("confirm", False)
+        
+        # Generate instruction using the helper method
+        instruction = self._generate_question_instruction(
+            question_text=question_text,
+            needs_confirmation=needs_confirmation,
+            is_first_question=True
+        )
+        
+        # Return a prompt to ask the question
+        return SwaigFunctionResult(instruction)
+    
+    @AgentBase.tool(
+        name="submit_answer",
+        description="Submit an answer to the current question and move to the next one",
+        parameters={
+            "answer": {
+                "type": "string",
+                "description": "The user's answer to the current question"
+            }
+        }
+    )
+    def submit_answer(self, args, raw_data):
+        """
+        Submit an answer to the current question and move to the next one
+        
+        This function:
+        1. Stores the answer in global_data
+        2. Increments the question index
+        3. Returns the next question or completion message
+        """
+        # Get the answer
+        answer = args.get("answer", "")
+        
+        # Get global data
+        global_data = raw_data.get("global_data", {})
+        questions = global_data.get("questions", [])
+        question_index = global_data.get("question_index", 0)
+        answers = global_data.get("answers", [])
+        
+        # Check if we're within bounds
+        if question_index >= len(questions):
+            return SwaigFunctionResult("All questions have already been answered.")
+        
+        # Get the current question
+        current_question = questions[question_index]
+        key_name = current_question.get("key_name", "")
+        
+        # Store the answer
+        new_answer = {"key_name": key_name, "answer": answer}
+        new_answers = answers + [new_answer]
+        
+        # Increment question index
+        new_question_index = question_index + 1
+        
+        print(f"new_question_index: {new_question_index} len(questions): {len(questions)}")
+        
+        # Check if we have more questions
+        if new_question_index < len(questions):
+
+            print(f"Asking next question: {new_question_index} question: {questions[new_question_index]}")
+            
+            # Get the next question
+            next_question = questions[new_question_index]
+            next_question_text = next_question.get("question_text", "")
+            needs_confirmation = next_question.get("confirm", False)
+            
+            # Generate instruction using the helper method
+            instruction = self._generate_question_instruction(
+                question_text=next_question_text,
+                needs_confirmation=needs_confirmation,
+                is_first_question=False
+            )
+            
+            # Create response with the global data update and next question
+            result = SwaigFunctionResult(instruction)
+            
+            # Add actions to update global data
+            result.add_actions([
+                {"set_global_data": {
+                    "answers": new_answers,
+                    "question_index": new_question_index
+                }}
+            ])
+            
+            return result
+        else:
+            # No more questions - create response with global data update and completion message
+            result = SwaigFunctionResult(
+                "Thank you! All questions have been answered. You can now summarize the information collected or ask if there's anything else the user would like to discuss."
+            )
+            
+            # Add actions to update global data
+            result.add_actions([
+                {"set_global_data": {
+                    "answers": new_answers,
+                    "question_index": new_question_index
+                }}
+            ])
+            
+            return result
+

signalwire_agents/prefabs/receptionist.py

@@ -0,0 +1,294 @@
+"""
+Copyright (c) 2025 SignalWire
+
+This file is part of the SignalWire AI Agents SDK.
+
+Licensed under the MIT License.
+See LICENSE file in the project root for full license information.
+"""
+
+"""
+ReceptionistAgent - Prefab agent for greeting callers and transferring them to appropriate departments
+"""
+
+from typing import List, Dict, Any, Optional, Union
+import json
+
+from signalwire_agents.core.agent_base import AgentBase
+from signalwire_agents.core.function_result import SwaigFunctionResult
+
+
+class ReceptionistAgent(AgentBase):
+    """
+    A prefab agent designed to act as a receptionist that:
+    1. Greets callers
+    2. Collects basic information about their needs
+    3. Transfers them to the appropriate department
+    
+    Example:
+        agent = ReceptionistAgent(
+            departments=[
+                {"name": "sales", "description": "For product inquiries, pricing, and purchasing", "number": "+15551235555"},
+                {"name": "support", "description": "For technical help and troubleshooting", "number": "+15551236666"}
+            ]
+        )
+    """
+    
+    def __init__(
+        self,
+        departments: List[Dict[str, str]],
+        name: str = "receptionist", 
+        route: str = "/receptionist",
+        greeting: str = "Thank you for calling. How can I help you today?",
+        voice: str = "elevenlabs.josh",
+        **kwargs
+    ):
+        """
+        Initialize a receptionist agent
+        
+        Args:
+            departments: List of departments to transfer to, each with:
+                - name: Department identifier (e.g., "sales")
+                - description: Description of department's purpose
+                - number: Phone number for transfer
+            name: Agent name for the route
+            route: HTTP route for this agent
+            greeting: Initial greeting message
+            voice: Voice ID to use
+            **kwargs: Additional arguments for AgentBase
+        """
+        # Initialize the base agent
+        super().__init__(
+            name=name,
+            route=route,
+            use_pom=True,
+            **kwargs
+        )
+        
+        # Validate departments format
+        self._validate_departments(departments)
+        
+        # Store greeting
+        self._greeting = greeting
+        
+        # Set up global data with departments and initial state
+        self.set_global_data({
+            "departments": departments,
+            "caller_info": {}
+        })
+        
+        # Build a prompt
+        self._build_prompt()
+        
+        # Configure agent settings
+        self._configure_agent_settings(voice)
+        
+        # Register tools
+        self._register_tools()
+    
+    def _validate_departments(self, departments):
+        """Validate that departments are in the correct format"""
+        if not departments:
+            raise ValueError("At least one department is required")
+            
+        for i, dept in enumerate(departments):
+            if "name" not in dept:
+                raise ValueError(f"Department {i+1} is missing 'name' field")
+            if "description" not in dept:
+                raise ValueError(f"Department {i+1} is missing 'description' field")
+            if "number" not in dept:
+                raise ValueError(f"Department {i+1} is missing 'number' field")
+    
+    def _build_prompt(self):
+        """Build the agent's prompt with personality, goals, and instructions"""
+        
+        # Set personality
+        self.prompt_add_section(
+            "Personality", 
+            body="You are a friendly and professional receptionist. You speak clearly and efficiently while maintaining a warm, helpful tone."
+        )
+        
+        # Set goal
+        self.prompt_add_section(
+            "Goal", 
+            body="Your goal is to greet callers, collect their basic information, and transfer them to the appropriate department."
+        )
+        
+        # Set instructions
+        self.prompt_add_section(
+            "Instructions", 
+            bullets=[
+                f"Begin by greeting the caller with: '{self._greeting}'",
+                "Collect their name and a brief description of their needs.",
+                "Based on their needs, determine which department would be most appropriate.",
+                "Use the collect_caller_info function when you have their name and reason for calling.",
+                "Use the transfer_call function to transfer them to the appropriate department.",
+                "Before transferring, always confirm with the caller that they're being transferred to the right department.",
+                "If a caller's request doesn't clearly match a department, ask follow-up questions to clarify."
+            ]
+        )
+        
+        # Add context with department information
+        global_data = self._global_data
+        departments = global_data.get("departments", [])
+        
+        department_bullets = []
+        for dept in departments:
+            department_bullets.append(f"{dept['name']}: {dept['description']}")
+        
+        self.prompt_add_section(
+            "Available Departments",
+            bullets=department_bullets
+        )
+        
+        # Add a post-prompt for summary generation
+        self.set_post_prompt("""
+        Return a JSON summary of the conversation:
+        {
+            "caller_name": "CALLER'S NAME",
+            "reason": "REASON FOR CALLING",
+            "department": "DEPARTMENT TRANSFERRED TO",
+            "satisfaction": "high/medium/low (estimated caller satisfaction)"
+        }
+        """)
+    
+    def _configure_agent_settings(self, voice):
+        """Configure additional agent settings"""
+        
+        # Set AI behavior parameters
+        self.set_params({
+            "end_of_speech_timeout": 700,
+            "speech_event_timeout": 1000,
+            "transfer_summary": True  # Enable call summary transfer between agents
+        })
+        
+        # Set language with specified voice
+        self.add_language(
+            name="English",
+            code="en-US",
+            voice=voice,
+            speech_fillers=["Let me get that information for you...", "One moment please..."],
+            function_fillers=["I'm processing that...", "Let me check which department can help you best..."]
+        )
+    
+    def _register_tools(self):
+        """Register the tools this agent needs"""
+        
+        # Define collect_caller_info tool
+        self.define_tool(
+            name="collect_caller_info",
+            description="Collect the caller's information for routing",
+            parameters={
+                "name": {
+                    "type": "string",
+                    "description": "The caller's name"
+                },
+                "reason": {
+                    "type": "string",
+                    "description": "The reason for the call"
+                }
+            },
+            handler=self._collect_caller_info_handler
+        )
+        
+        # Define transfer_call tool
+        # First, get the department names from global data
+        global_data = self._global_data
+        departments = global_data.get("departments", [])
+        department_names = [dept["name"] for dept in departments]
+        
+        self.define_tool(
+            name="transfer_call",
+            description="Transfer the caller to the appropriate department",
+            parameters={
+                "department": {
+                    "type": "string",
+                    "description": "The department to transfer to",
+                    "enum": department_names
+                }
+            },
+            handler=self._transfer_call_handler
+        )
+    
+    def _collect_caller_info_handler(self, args, raw_data):
+        """Handler for collect_caller_info tool"""
+        
+        # Get the caller info
+        name = args.get("name", "")
+        reason = args.get("reason", "")
+        
+        # Create response with global data update
+        result = SwaigFunctionResult(
+            f"Thank you, {name}. I've noted that you're calling about {reason}."
+        )
+        
+        # Update global data with caller info
+        result.add_actions([
+            {"set_global_data": {
+                "caller_info": {
+                    "name": name,
+                    "reason": reason
+                }
+            }}
+        ])
+        
+        return result
+    
+    def _transfer_call_handler(self, args, raw_data):
+        """Handler for transfer_call tool"""
+        
+        # Get the department
+        department_name = args.get("department", "")
+        
+        # Get global data
+        global_data = raw_data.get("global_data", {})
+        caller_info = global_data.get("caller_info", {})
+        name = caller_info.get("name", "the caller")
+        departments = global_data.get("departments", [])
+        
+        # Find the department in the list
+        department = None
+        for dept in departments:
+            if dept["name"] == department_name:
+                department = dept
+                break
+        
+        # If department not found, return error
+        if not department:
+            return SwaigFunctionResult(f"Sorry, I couldn't find the {department_name} department.")
+        
+        # Get transfer number
+        transfer_number = department.get("number", "")
+        
+        # Create message for caller
+        message = f"I'll transfer you to our {department_name} department now. Thank you for calling, {name}!"
+        
+        # Create result with transfer SWML
+        result = SwaigFunctionResult(message)
+        
+        # Add the SWML to execute the transfer
+        result.add_swml([
+            {
+                "play": {
+                    "url": f"say:{message}"
+                }
+            },
+            {
+                "connect": {
+                    "to": transfer_number
+                }
+            }
+        ])
+        
+        return result
+        
+    def on_summary(self, summary, raw_data=None):
+        """
+        Process the conversation summary
+        
+        Args:
+            summary: Summary data from the conversation
+            raw_data: The complete raw POST data from the request
+        """
+        # Subclasses can override this to handle the summary
+        pass