signalwire.prefabs¶

`signalwire.prefabs` ¶

This file is part of the SignalWire SDK.

Licensed under the MIT License. See LICENSE file in the project root for full license information.

Prefab agents with specific functionality that can be used out-of-the-box

`all = ['ConciergeAgent', 'FAQBotAgent', 'InfoGathererAgent', 'ReceptionistAgent', 'SurveyAgent']` `module-attribute` ¶

`InfoGathererAgent` ¶

Bases: 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?"} ] )

`init(questions=None, name='info_gatherer', route='/info_gatherer', **kwargs)` ¶

Initialize an information gathering agent

Parameters:

Name	Type	Description	Default
`questions`	`list[dict[str, str]] \| None`	Optional list of questions to ask. If None, questions will be determined dynamically via a callback function. Each question dict should have: - 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	`None`
`name`	`str`	Agent name for the route	`'info_gatherer'`
`route`	`str`	HTTP route for this agent	`'/info_gatherer'`
`**kwargs`	`Any`	Additional arguments for AgentBase	`{}`

`set_question_callback(callback)` ¶

Set a callback function for dynamic question configuration

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[dict[str, Any], dict[str, Any], dict[str, Any]], list[dict[str, str]]]`	Function that takes (query_params, body_params, headers) and returns a list of question dictionaries. Each question dict should have: - key_name: Identifier for storing the answer - question_text: The actual question to ask the user - confirm: (Optional) If True, agent will confirm answer before submitting	required

Example

def my_question_callback(query_params, body_params, headers): question_set = query_params.get('set', 'default') if question_set == 'support': return [ {"key_name": "name", "question_text": "What is your name?"}, {"key_name": "issue", "question_text": "What's the issue?"} ] else: return [{"key_name": "name", "question_text": "What is your name?"}]

agent.set_question_callback(my_question_callback)

`on_swml_request(request_data=None, callback_path=None, request=None)` ¶

Handle dynamic configuration using the callback function

This method is called when SWML is requested and allows us to configure the agent just-in-time using the provided callback.

`start_questions(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.

`submit_answer(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

`FAQBotAgent` ¶

Bases: AgentBase

A prefab agent designed to answer frequently asked questions based on a provided list of question/answer pairs.

This agent will: 1. Match user questions against the FAQ database 2. Provide the most relevant answer 3. Suggest other relevant questions when appropriate

Example

agent = FAQBotAgent( faqs=[ { "question": "What is SignalWire?", "answer": "SignalWire is a developer-friendly cloud communications platform." }, { "question": "How much does it cost?", "answer": "SignalWire offers pay-as-you-go pricing with no monthly fees." } ] )

`faqs = faqs` `instance-attribute` ¶

`suggest_related = suggest_related` `instance-attribute` ¶

`persona = persona or 'You are a helpful FAQ bot that provides accurate answers to common questions.'` `instance-attribute` ¶

`init(faqs, suggest_related=True, persona=None, name='faq_bot', route='/faq', **kwargs)` ¶

Initialize an FAQ bot agent

Parameters:

Name	Type	Description	Default
`faqs`	`list[dict[str, Any]]`	List of FAQ items, each with: - question: The question text - answer: The answer text - categories: Optional list of category tags	required
`suggest_related`	`bool`	Whether to suggest related questions	`True`
`persona`	`str \| None`	Optional custom personality description	`None`
`name`	`str`	Agent name for the route	`'faq_bot'`
`route`	`str`	HTTP route for this agent	`'/faq'`
`**kwargs`	`Any`	Additional arguments for AgentBase	`{}`

`search_faqs(args, raw_data)` ¶

Search for FAQs matching a specific query or category

This function helps find relevant FAQs based on a search query or category. It returns matching FAQs in order of relevance.

`on_summary(summary, raw_data=None)` ¶

Process the interaction summary

Parameters:

Name	Type	Description	Default
`summary`	`dict[str, Any] \| None`	Summary data from the conversation	required
`raw_data`	`dict[str, Any] \| None`	The complete raw POST data from the request	`None`

`ConciergeAgent` ¶

Bases: AgentBase

A prefab agent designed to act as a virtual concierge, providing information and services to users.

This agent will: 1. Welcome users and explain available services 2. Answer questions about amenities, hours, and directions 3. Help with bookings and reservations 4. Provide personalized recommendations

Example

agent = ConciergeAgent( venue_name="Grand Hotel", services=["room service", "spa bookings", "restaurant reservations"], amenities={ "pool": {"hours": "7 AM - 10 PM", "location": "2nd Floor"}, "gym": {"hours": "24 hours", "location": "3rd Floor"} } )

`venue_name = venue_name` `instance-attribute` ¶

`services = services` `instance-attribute` ¶

`amenities = amenities` `instance-attribute` ¶

`hours_of_operation = hours_of_operation or {'default': '9 AM - 5 PM'}` `instance-attribute` ¶

`special_instructions = special_instructions or []` `instance-attribute` ¶

`init(venue_name, services, amenities, hours_of_operation=None, special_instructions=None, welcome_message=None, name='concierge', route='/concierge', **kwargs)` ¶

Initialize a concierge agent

Parameters:

Name	Type	Description	Default
`venue_name`	`str`	Name of the venue or business	required
`services`	`list[str]`	List of services offered	required
`amenities`	`dict[str, dict[str, str]]`	Dictionary of amenities with details	required
`hours_of_operation`	`dict[str, str] \| None`	Optional dictionary of operating hours	`None`
`special_instructions`	`list[str] \| None`	Optional list of special instructions	`None`
`welcome_message`	`str \| None`	Optional custom welcome message	`None`
`name`	`str`	Agent name for the route	`'concierge'`
`route`	`str`	HTTP route for this agent	`'/concierge'`
`**kwargs`	`Any`	Additional arguments for AgentBase	`{}`

`check_availability(args, raw_data)` ¶

Check availability for a service on a specific date and time

This is a simulated function that would typically connect to a real booking system. In this example, it returns a mock availability response.

`get_directions(args, raw_data)` ¶

Provide directions to a specific location or amenity

`on_summary(summary, raw_data=None)` ¶

Process the interaction summary

Parameters:

Name	Type	Description	Default
`summary`	`dict[str, Any] \| None`	Summary data from the conversation	required
`raw_data`	`dict[str, Any] \| None`	The complete raw POST data from the request	`None`

`SurveyAgent` ¶

Bases: AgentBase

A prefab agent designed to conduct automated surveys with users.

This agent will: 1. Introduce the survey purpose and structure 2. Ask predefined questions in sequence 3. Collect and validate responses 4. Provide a summary of collected responses

Example

agent = SurveyAgent( survey_name="Customer Satisfaction Survey", introduction="We'd like to get your feedback on your recent experience.", questions=[ { "id": "satisfaction", "text": "How satisfied were you with our service?", "type": "rating", "scale": 5, "required": True }, { "id": "comments", "text": "Do you have any additional comments?", "type": "open_ended", "required": False } ] )

`survey_name = survey_name` `instance-attribute` ¶

`questions = questions` `instance-attribute` ¶

`brand_name = brand_name or 'Our Company'` `instance-attribute` ¶

`max_retries = max_retries` `instance-attribute` ¶

`introduction = introduction or f'Welcome to our {survey_name}. We appreciate your participation.'` `instance-attribute` ¶

`conclusion = conclusion or 'Thank you for completing our survey. Your feedback is valuable to us.'` `instance-attribute` ¶

`init(survey_name, questions, introduction=None, conclusion=None, brand_name=None, max_retries=2, name='survey', route='/survey', **kwargs)` ¶

Initialize a survey agent

Parameters:

Name	Type	Description	Default
`survey_name`	`str`	Name of the survey	required
`questions`	`list[dict[str, Any]]`	List of question objects with the following keys: - id: Unique identifier for the question - text: The question text to ask - type: Type of question (rating, multiple_choice, yes_no, open_ended) - options: List of options for multiple_choice questions - scale: For rating questions, the scale (e.g., 1-5) - required: Whether the question requires an answer	required
`introduction`	`str \| None`	Optional custom introduction message	`None`
`conclusion`	`str \| None`	Optional custom conclusion message	`None`
`brand_name`	`str \| None`	Optional brand or company name	`None`
`max_retries`	`int`	Maximum number of times to retry invalid answers	`2`
`name`	`str`	Name for the agent (default: "survey")	`'survey'`
`route`	`str`	HTTP route for the agent (default: "/survey")	`'/survey'`
`**kwargs`	`Any`	Additional arguments for AgentBase	`{}`

`validate_response(args, raw_data)` ¶

Validate if a response meets the requirements for a specific question

This function checks if a user's response is valid for the specified question based on the question type and constraints.

`log_response(args, raw_data)` ¶

Log a validated response to a survey question

This function would typically connect to a database or API to store the response. In this example, it just acknowledges that the response was received.

`on_summary(summary, raw_data=None)` ¶

Process the survey results summary

Parameters:

Name	Type	Description	Default
`summary`	`dict[str, Any] \| None`	Summary data containing survey responses	required
`raw_data`	`dict[str, Any] \| None`	The complete raw POST data from the request	`None`

`ReceptionistAgent` ¶

Bases: 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"} ] )

`init(departments, name='receptionist', route='/receptionist', greeting='Thank you for calling. How can I help you today?', voice='rime.spore', **kwargs)` ¶

Initialize a receptionist agent

Parameters:

Name	Type	Description	Default
`departments`	`list[dict[str, str]]`	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	required
`name`	`str`	Agent name for the route	`'receptionist'`
`route`	`str`	HTTP route for this agent	`'/receptionist'`
`greeting`	`str`	Initial greeting message	`'Thank you for calling. How can I help you today?'`
`voice`	`str`	Voice ID to use	`'rime.spore'`
`**kwargs`	`Any`	Additional arguments for AgentBase	`{}`

`on_summary(summary, raw_data=None)` ¶

Process the conversation summary

Parameters:

Name	Type	Description	Default
`summary`	`dict[str, Any] \| None`	Summary data from the conversation	required
`raw_data`	`dict[str, Any] \| None`	The complete raw POST data from the request	`None`

`concierge` ¶

This file is part of the SignalWire SDK.

Licensed under the MIT License. See LICENSE file in the project root for full license information.

ConciergeAgent - Prefab agent for providing virtual concierge services

`ConciergeAgent` ¶

Bases: AgentBase

A prefab agent designed to act as a virtual concierge, providing information and services to users.

This agent will: 1. Welcome users and explain available services 2. Answer questions about amenities, hours, and directions 3. Help with bookings and reservations 4. Provide personalized recommendations

Example

agent = ConciergeAgent( venue_name="Grand Hotel", services=["room service", "spa bookings", "restaurant reservations"], amenities={ "pool": {"hours": "7 AM - 10 PM", "location": "2nd Floor"}, "gym": {"hours": "24 hours", "location": "3rd Floor"} } )

`venue_name = venue_name` `instance-attribute` ¶

`services = services` `instance-attribute` ¶

`amenities = amenities` `instance-attribute` ¶

`hours_of_operation = hours_of_operation or {'default': '9 AM - 5 PM'}` `instance-attribute` ¶

`special_instructions = special_instructions or []` `instance-attribute` ¶

`init(venue_name, services, amenities, hours_of_operation=None, special_instructions=None, welcome_message=None, name='concierge', route='/concierge', **kwargs)` ¶

Initialize a concierge agent

Parameters:

Name	Type	Description	Default
`venue_name`	`str`	Name of the venue or business	required
`services`	`list[str]`	List of services offered	required
`amenities`	`dict[str, dict[str, str]]`	Dictionary of amenities with details	required
`hours_of_operation`	`dict[str, str] \| None`	Optional dictionary of operating hours	`None`
`special_instructions`	`list[str] \| None`	Optional list of special instructions	`None`
`welcome_message`	`str \| None`	Optional custom welcome message	`None`
`name`	`str`	Agent name for the route	`'concierge'`
`route`	`str`	HTTP route for this agent	`'/concierge'`
`**kwargs`	`Any`	Additional arguments for AgentBase	`{}`

`check_availability(args, raw_data)` ¶

Check availability for a service on a specific date and time

This is a simulated function that would typically connect to a real booking system. In this example, it returns a mock availability response.

`get_directions(args, raw_data)` ¶

Provide directions to a specific location or amenity

`on_summary(summary, raw_data=None)` ¶

Process the interaction summary

Parameters:

Name	Type	Description	Default
`summary`	`dict[str, Any] \| None`	Summary data from the conversation	required
`raw_data`	`dict[str, Any] \| None`	The complete raw POST data from the request	`None`

`faq_bot` ¶

This file is part of the SignalWire SDK.

Licensed under the MIT License. See LICENSE file in the project root for full license information.

FAQBotAgent - Prefab agent for answering frequently asked questions

`FAQBotAgent` ¶

Bases: AgentBase

A prefab agent designed to answer frequently asked questions based on a provided list of question/answer pairs.

This agent will: 1. Match user questions against the FAQ database 2. Provide the most relevant answer 3. Suggest other relevant questions when appropriate

Example

agent = FAQBotAgent( faqs=[ { "question": "What is SignalWire?", "answer": "SignalWire is a developer-friendly cloud communications platform." }, { "question": "How much does it cost?", "answer": "SignalWire offers pay-as-you-go pricing with no monthly fees." } ] )

`faqs = faqs` `instance-attribute` ¶

`suggest_related = suggest_related` `instance-attribute` ¶

`persona = persona or 'You are a helpful FAQ bot that provides accurate answers to common questions.'` `instance-attribute` ¶

`init(faqs, suggest_related=True, persona=None, name='faq_bot', route='/faq', **kwargs)` ¶

Initialize an FAQ bot agent

Parameters:

Name	Type	Description	Default
`faqs`	`list[dict[str, Any]]`	List of FAQ items, each with: - question: The question text - answer: The answer text - categories: Optional list of category tags	required
`suggest_related`	`bool`	Whether to suggest related questions	`True`
`persona`	`str \| None`	Optional custom personality description	`None`
`name`	`str`	Agent name for the route	`'faq_bot'`
`route`	`str`	HTTP route for this agent	`'/faq'`
`**kwargs`	`Any`	Additional arguments for AgentBase	`{}`

`search_faqs(args, raw_data)` ¶

Search for FAQs matching a specific query or category

This function helps find relevant FAQs based on a search query or category. It returns matching FAQs in order of relevance.

`on_summary(summary, raw_data=None)` ¶

Process the interaction summary

Parameters:

Name	Type	Description	Default
`summary`	`dict[str, Any] \| None`	Summary data from the conversation	required
`raw_data`	`dict[str, Any] \| None`	The complete raw POST data from the request	`None`

`info_gatherer` ¶

This file is part of the SignalWire 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

Supports both static (questions provided at init) and dynamic (questions determined by a callback function) configuration modes.

`InfoGathererAgent` ¶

Bases: 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?"} ] )

`init(questions=None, name='info_gatherer', route='/info_gatherer', **kwargs)` ¶

Initialize an information gathering agent

Parameters:

Name	Type	Description	Default
`questions`	`list[dict[str, str]] \| None`	Optional list of questions to ask. If None, questions will be determined dynamically via a callback function. Each question dict should have: - 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	`None`
`name`	`str`	Agent name for the route	`'info_gatherer'`
`route`	`str`	HTTP route for this agent	`'/info_gatherer'`
`**kwargs`	`Any`	Additional arguments for AgentBase	`{}`

`set_question_callback(callback)` ¶

Set a callback function for dynamic question configuration

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[dict[str, Any], dict[str, Any], dict[str, Any]], list[dict[str, str]]]`	Function that takes (query_params, body_params, headers) and returns a list of question dictionaries. Each question dict should have: - key_name: Identifier for storing the answer - question_text: The actual question to ask the user - confirm: (Optional) If True, agent will confirm answer before submitting	required

Example

def my_question_callback(query_params, body_params, headers): question_set = query_params.get('set', 'default') if question_set == 'support': return [ {"key_name": "name", "question_text": "What is your name?"}, {"key_name": "issue", "question_text": "What's the issue?"} ] else: return [{"key_name": "name", "question_text": "What is your name?"}]

agent.set_question_callback(my_question_callback)

`on_swml_request(request_data=None, callback_path=None, request=None)` ¶

Handle dynamic configuration using the callback function

This method is called when SWML is requested and allows us to configure the agent just-in-time using the provided callback.

`start_questions(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.

`submit_answer(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

`receptionist` ¶

This file is part of the SignalWire 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

`ReceptionistAgent` ¶

Bases: 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"} ] )

`init(departments, name='receptionist', route='/receptionist', greeting='Thank you for calling. How can I help you today?', voice='rime.spore', **kwargs)` ¶

Initialize a receptionist agent

Parameters:

Name	Type	Description	Default
`departments`	`list[dict[str, str]]`	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	required
`name`	`str`	Agent name for the route	`'receptionist'`
`route`	`str`	HTTP route for this agent	`'/receptionist'`
`greeting`	`str`	Initial greeting message	`'Thank you for calling. How can I help you today?'`
`voice`	`str`	Voice ID to use	`'rime.spore'`
`**kwargs`	`Any`	Additional arguments for AgentBase	`{}`

`on_summary(summary, raw_data=None)` ¶

Process the conversation summary

Parameters:

Name	Type	Description	Default
`summary`	`dict[str, Any] \| None`	Summary data from the conversation	required
`raw_data`	`dict[str, Any] \| None`	The complete raw POST data from the request	`None`

`survey` ¶

This file is part of the SignalWire SDK.

Licensed under the MIT License. See LICENSE file in the project root for full license information.

SurveyAgent - Prefab agent for conducting automated surveys

`SurveyAgent` ¶

Bases: AgentBase

A prefab agent designed to conduct automated surveys with users.

This agent will: 1. Introduce the survey purpose and structure 2. Ask predefined questions in sequence 3. Collect and validate responses 4. Provide a summary of collected responses

Example

agent = SurveyAgent( survey_name="Customer Satisfaction Survey", introduction="We'd like to get your feedback on your recent experience.", questions=[ { "id": "satisfaction", "text": "How satisfied were you with our service?", "type": "rating", "scale": 5, "required": True }, { "id": "comments", "text": "Do you have any additional comments?", "type": "open_ended", "required": False } ] )

`survey_name = survey_name` `instance-attribute` ¶

`questions = questions` `instance-attribute` ¶

`brand_name = brand_name or 'Our Company'` `instance-attribute` ¶

`max_retries = max_retries` `instance-attribute` ¶

`introduction = introduction or f'Welcome to our {survey_name}. We appreciate your participation.'` `instance-attribute` ¶

`conclusion = conclusion or 'Thank you for completing our survey. Your feedback is valuable to us.'` `instance-attribute` ¶

`init(survey_name, questions, introduction=None, conclusion=None, brand_name=None, max_retries=2, name='survey', route='/survey', **kwargs)` ¶

Initialize a survey agent

Parameters:

Name	Type	Description	Default
`survey_name`	`str`	Name of the survey	required
`questions`	`list[dict[str, Any]]`	List of question objects with the following keys: - id: Unique identifier for the question - text: The question text to ask - type: Type of question (rating, multiple_choice, yes_no, open_ended) - options: List of options for multiple_choice questions - scale: For rating questions, the scale (e.g., 1-5) - required: Whether the question requires an answer	required
`introduction`	`str \| None`	Optional custom introduction message	`None`
`conclusion`	`str \| None`	Optional custom conclusion message	`None`
`brand_name`	`str \| None`	Optional brand or company name	`None`
`max_retries`	`int`	Maximum number of times to retry invalid answers	`2`
`name`	`str`	Name for the agent (default: "survey")	`'survey'`
`route`	`str`	HTTP route for the agent (default: "/survey")	`'/survey'`
`**kwargs`	`Any`	Additional arguments for AgentBase	`{}`

`validate_response(args, raw_data)` ¶

Validate if a response meets the requirements for a specific question

This function checks if a user's response is valid for the specified question based on the question type and constraints.

`log_response(args, raw_data)` ¶

Log a validated response to a survey question

This function would typically connect to a database or API to store the response. In this example, it just acknowledges that the response was received.

`on_summary(summary, raw_data=None)` ¶

Process the survey results summary

Parameters:

Name	Type	Description	Default
`summary`	`dict[str, Any] \| None`	Summary data containing survey responses	required
`raw_data`	`dict[str, Any] \| None`	The complete raw POST data from the request	`None`

signalwire.prefabs¶