***

id: 9beff876-7742-4903-9a5c-b548e2ae2d3e
title: Survey
sidebar-title: Survey
slug: /python/guides/survey
max-toc-depth: 3
----------------

## Survey

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

### Basic Usage

```python
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

```python
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

<Frame caption="Survey Flow">
  <img class="diagram" src="https://files.buildwithfern.com/signalwire.docs.buildwithfern.com/docs/652be6e495d096adb742e085040e48bb9502e5c4a6dd436ebe2341463426e341/assets/images/agents-sdk-manual/09_03_survey_diagram1.webp" alt="Survey Flow." />
</Frame>

### Complete Example

```python
#!/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