Survey

Survey

Summary: SurveyAgent conducts automated surveys with different question types (rating, multiple choice, yes/no, open-ended), validation, and response logging.

Basic Usage

from signalwire_agents.prefabs import SurveyAgent

agent = SurveyAgent(
    survey_name="Customer Satisfaction Survey",
    questions=[
        {
            "id": "satisfaction",
            "text": "How satisfied were you with our service?",
            "type": "rating",
            "scale": 5
        },
        {
            "id": "recommend",
            "text": "Would you recommend us to others?",
            "type": "yes_no"
        },
        {
            "id": "comments",
            "text": "Any additional comments?",
            "type": "open_ended",
            "required": False
        }
    ]
)

if __name__ == "__main__":
    agent.run()

Question Types

Type	Fields	Example
rating	scale (1-10)	"Rate 1-5, where 5 is best"
multiple_choice	options (list)	"Choose: Poor, Fair, Good, Excellent"
yes_no	(none)	"Would you recommend us?"
open_ended	(none)	"Any comments?"

Question Format

Field	Type	Required	Description
id	string	Yes	Unique identifier for the question
text	string	Yes	The question to ask
type	string	Yes	rating, multiple_choice, yes_no, open_ended
options	list[string]	*	Required for multiple_choice
scale	integer	No	For rating (default: 5)
required	boolean	No	Is answer required (default: true)

Constructor Parameters

SurveyAgent(
    survey_name="...",         # Name of the survey (required)
    questions=[...],           # List of question dictionaries (required)
    introduction=None,         # Custom intro message
    conclusion=None,           # Custom conclusion message
    brand_name=None,           # Company/brand name
    max_retries=2,             # Retries for invalid answers
    name="survey",             # Agent name
    route="/survey",           # HTTP route
    **kwargs                   # Additional AgentBase arguments
)

Built-in Functions

SurveyAgent provides these SWAIG functions automatically:

Function	Description
validate_response	Check if response is valid for question type
log_response	Record a validated response

Survey Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                     Survey Flow                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  1. Introduction                                                            │
│      │                                                                      │
│      ▼                                                                      │
│  2. Ask question                                                            │
│      │                                                                      │
│      ▼                                                                      │
│  3. Get response                                                            │
│      │                                                                      │
│      ├── Valid → Log and continue                                           │
│      │                                                                      │
│      └── Invalid → Retry (up to max_retries)                                │
│              │                                                              │
│              └── Still invalid → Skip or ask again                          │
│      │                                                                      │
│      ▼                                                                      │
│  4. Next question (repeat 2-3)                                              │
│      │                                                                      │
│      ▼                                                                      │
│  5. Conclusion                                                              │
│      │                                                                      │
│      ▼                                                                      │
│  6. Generate summary                                                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Complete Example

#!/usr/bin/env python3
## product_survey.py - Product feedback survey agent
from signalwire_agents.prefabs import SurveyAgent


agent = SurveyAgent(
    survey_name="Product Feedback Survey",
    brand_name="TechGadgets Inc.",
    introduction="Thank you for purchasing our product. We'd love your feedback!",
    conclusion="Thank you for completing our survey. Your input helps us improve.",
    questions=[
        {
            "id": "overall_rating",
            "text": "How would you rate the product overall?",
            "type": "rating",
            "scale": 5,
            "required": True
        },
        {
            "id": "quality",
            "text": "How would you rate the build quality?",
            "type": "multiple_choice",
            "options": ["Poor", "Fair", "Good", "Excellent"],
            "required": True
        },
        {
            "id": "purchase_again",
            "text": "Would you purchase from us again?",
            "type": "yes_no",
            "required": True
        },
        {
            "id": "improvements",
            "text": "What could we improve?",
            "type": "open_ended",
            "required": False
        }
    ],
    max_retries=2
)

if __name__ == "__main__":
    agent.add_language("English", "en-US", "rime.spore")
    agent.run()

Best Practices

Question Design

• Keep surveys short (5-7 questions max)
• Start with easy questions
• Put open-ended questions at the end
• Make non-essential questions optional

Question Types

• Use rating for satisfaction metrics (NPS, CSAT)
• Use multiple_choice for specific options
• Use yes_no for simple binary questions
• Use open_ended sparingly - harder to analyze

Validation

• Set appropriate max_retries (2-3)
• Use clear scale descriptions
• List all options for multiple choice