SurveyAgent | SignalWire

Conducts automated surveys with support for multiple question types, response validation, and structured result summaries. The agent guides users through each question in sequence, validates answers based on the question type, and retries on invalid responses.

1 from signalwire.prefabs import SurveyAgent

survey_name

strRequired

Name of the survey. Used in the agent’s prompt and summary output.

questions

list[dict]Required

List of survey questions. Each dict must have id, text, and type:

questions[].id

strRequired

Unique identifier for the question (e.g., "satisfaction"). Auto-generated as question_N if omitted.

questions[].text

strRequired

The question text to ask the user.

questions[].type

strRequired

Question type. Valid values:

"rating" — numeric scale (1 to scale)
"multiple_choice" — select from options list
"yes_no" — accepts yes/no/y/n
"open_ended" — free text response

questions[].options

list[str]

Required for multiple_choice questions. List of valid answer options.

questions[].scale

intDefaults to 5

For rating questions, the maximum value on the scale (e.g., 5 for 1-5).

questions[].required

boolDefaults to True

Whether the question requires an answer. Non-required open_ended questions accept empty responses.

introduction

str

Custom introduction message. Defaults to "Welcome to our {survey_name}.".

conclusion

str

Custom conclusion message. Defaults to "Thank you for completing our survey.".

brand_name

strDefaults to Our Company

Company or brand name used in the agent’s persona.

max_retries

intDefaults to 2

Maximum number of times to re-ask a question after an invalid response.

name

strDefaults to survey

Agent name for identification and logging.

route

strDefaults to /survey

HTTP route for this agent.

Built-in Tools

Tool	Description	Parameters
`validate_response`	Check if a response meets the question’s requirements	`question_id` (str), `response` (str)
`log_response`	Record a validated response	`question_id` (str), `response` (str)

Example

1 from signalwire.prefabs import SurveyAgent
2 
3 agent = SurveyAgent(
4     survey_name="Product Feedback Survey",
5     brand_name="TechGadgets Inc.",
6     introduction="Thank you for purchasing our product. We'd love your feedback!",
7     conclusion="Thank you for completing our survey. Your input helps us improve.",
8     questions=[
9         {
10             "id": "overall_rating",
11             "text": "How would you rate the product overall?",
12             "type": "rating",
13             "scale": 5
14         },
15         {
16             "id": "quality",
17             "text": "How would you rate the build quality?",
18             "type": "multiple_choice",
19             "options": ["Poor", "Fair", "Good", "Excellent"]
20         },
21         {
22             "id": "purchase_again",
23             "text": "Would you purchase from us again?",
24             "type": "yes_no"
25         },
26         {
27             "id": "improvements",
28             "text": "What could we improve?",
29             "type": "open_ended",
30             "required": False
31         }
32     ],
33     max_retries=2
34 )
35 
36 agent.add_language("English", "en-US", "rime.spore")
37 
38 if __name__ == "__main__":
39     agent.run()