The SignalWire AI Agents SDK provides a Python framework for building, deploying, and managing AI agents as microservices. These agents are self-contained web applications that expose HTTP endpoints to interact with the SignalWire platform. The SDK simplifies the creation of custom AI agents by handling common functionality like HTTP routing, prompt management, and tool execution.
The SDK is built around a clear class hierarchy:
Document rendering and serving
Prompt Object Model (POM)
Programmatic prompt construction and manipulation
SWAIG Function Framework
Handler registry for function execution
HTTP Routing
Basic authentication
State Management
State lifecycle hooks (startup, hangup)
Prefab Agents
Extensible designs for common use cases
Skills System
The DataMap system provides a declarative approach to creating SWAIG tools that integrate with REST APIs without requiring custom webhook infrastructure. DataMap tools execute on SignalWire's server infrastructure, simplifying deployment and eliminating the need to expose webhook endpoints.
DataMap tools follow a pipeline execution model on the SignalWire server:
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Function Call │ │ Expression │ │ Webhook │ │ Response │
│ (Arguments) │━━━▶│ Processing │━━━▶│ Execution │━━━▶│ Generation │
└─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │ │
│ │ │ │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│Variable │ │Pattern │ │HTTP │ │Template │
│Expansion│ │Matching │ │Request │ │Rendering│
│ │ │ │ │ │ │ │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
Builder Pattern: Fluent interface for constructing data_map configurations
python
tool = (DataMap('function_name')
.description('Function purpose')
.parameter('param', 'string', 'Description', required=True)
.webhook('GET', 'https://api.example.com/endpoint')
.output(SwaigFunctionResult('Response template'))
)
Processing Pipeline: Ordered execution with early termination
Output: Final response generation using SwaigFunctionResult
Variable Expansion: Dynamic substitution using ${variable} syntax
${args.parameter_name}${response.field.nested_field}${foreach.item_field}${global_data.key}${meta_data.call_id}The system supports different tool patterns:
API Integration Tools: Direct REST API calls
python
weather_tool = (DataMap('get_weather')
.webhook('GET', 'https://api.weather.com/v1/current?q=${location}')
.output(SwaigFunctionResult('Weather: ${response.current.condition}'))
)
Expression-Based Tools: Pattern matching without API calls
python
control_tool = (DataMap('file_control')
.expression(r'start.*', SwaigFunctionResult().add_action('start', True))
.expression(r'stop.*', SwaigFunctionResult().add_action('stop', True))
)
Array Processing Tools: Handle list responses
python
search_tool = (DataMap('search_docs')
.webhook('GET', 'https://api.docs.com/search')
.foreach('${response.results}')
.output(SwaigFunctionResult('Found: ${foreach.title}'))
)
DataMap tools integrate seamlessly with the existing agent architecture:
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ AgentBase │ │ SWAIG │ │ SignalWire │
│ │ │ Function │ │ Server │
│ .register_ │━━━▶│ Registry │━━━▶│ Execution │
│ swaig_function │ │ │ │ Environment │
│ │ │ data_map field │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
│ │ │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│DataMap │ │Function │ │Variable │
│Builder │ │Definition│ │Expansion│
│ │ │ │ │ │
└─────────┘ └─────────┘ └─────────┘
DataMap configurations use a hierarchical structure:
{
"function": "tool_name",
"description": "Tool description",
"parameters": {
"type": "object",
"properties": {...},
"required": [...]
},
"data_map": {
"expressions": [...],
"webhooks": [...],
"foreach": "path",
"output": {...},
"error_keys": [...]
}
}
This structure separates: - Function Metadata: Name, description, parameters - Processing Logic: Expressions, webhooks, array handling - Output Definition: Response templates and actions
Benefits:
Trade-offs:
When to Choose DataMap vs Skills vs Custom Tools:
The Skills System provides a modular architecture for extending agent capabilities through self-contained, reusable components. Skills are automatically discovered, validated, and can be configured with parameters.
The skills system follows a three-layer architecture:
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Agent Layer │ │ Management │ │ Skills Layer │
│ │ │ Layer │ │ │
│ AgentBase │━━━▶│ SkillManager │━━━▶│ SkillBase │
│ .add_skill() │ │ .load_skill() │ │ .setup() │
│ │ │ .unload_skill() │ │ .register_tools()│
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
│ │ │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│Request │ │Registry │ │Skill │
│Routing │ │Discovery│ │Instance │
│ │ │ │ │ │
└─────────┘ └─────────┘ └─────────┘
Lifecycle management (setup, cleanup)
SkillManager: Manages skill loading and lifecycle
Integration with agent prompt and tool systems
SkillRegistry: Automatic skill discovery system
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Discovery │ │ Loading │ │ Registration │
│ │ │ │ │ │
│ 1. Scan dirs │━━━▶│ 1. Validate │━━━▶│ 1. Add tools │
│ 2. Import mods │ │ deps │ │ 2. Add prompts │
│ 3. Find classes │ │ 2. Create │ │ 3. Add hints │
│ 4. Register │ │ instance │ │ 4. Store ref │
│ │ │ 3. Call setup() │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Skills support configurable parameters for customization:
# Default behavior
agent.add_skill("web_search")
# Custom configuration
agent.add_skill("web_search", {
"num_results": 3,
"delay": 0.5
})
Parameters are passed to the skill constructor and accessible via self.params:
class WebSearchSkill(SkillBase):
def setup(self) -> bool:
self.num_results = self.params.get('num_results', 1)
self.delay = self.params.get('delay', 0)
# Configure behavior based on parameters
The system provides detailed error reporting for common issues:
Error messages are actionable and specific:
Failed to load skill 'web_search': Missing required environment variables: ['GOOGLE_SEARCH_API_KEY', 'GOOGLE_SEARCH_ENGINE_ID']
Skills integrate seamlessly with existing agent systems:
This architecture enables powerful one-liner integration while maintaining flexibility and extensibility.
The SDK implements a multi-layer security model:
SSL certificate configuration
Authentication
Configurable via environment variables or programmatically
Authorization
secure=True option on tool definitions (default)
State Isolation
The SDK is designed to be highly extensible:
Custom Agents: Extend AgentBase to create specialized agents
python
class CustomAgent(AgentBase):
def __init__(self):
super().__init__(name="custom", route="/custom")
Tool Registration: Add new tools using the decorator pattern
python
@AgentBase.tool(
name="tool_name",
description="Tool description",
parameters={...},
secure=True
)
def my_tool(self, args, raw_data):
# Tool implementation
Prompt Customization: Add sections, hints, languages
python
agent.add_language(name="English", code="en-US", voice="elevenlabs.josh")
agent.add_hints(["SignalWire", "SWML", "SWAIG"])
State Management: Implement custom state persistence
python
class CustomStateManager(StateManager):
def get_state(self, call_id):
# Implementation
Request Handling: Override request handling methods
python
def on_swml_request(self, request_data):
# Custom request handling
Custom Prefabs: Create reusable agent patterns
python
class MyCustomPrefab(AgentBase):
def __init__(self, config_param1, config_param2, **kwargs):
super().__init__(**kwargs)
# Configure the agent based on parameters
self.prompt_add_section("Personality", body=f"Customized based on: {config_param1}")
Dynamic Configuration: Per-request agent configuration for flexible behavior ```python def configure_agent_dynamically(self, query_params, body_params, headers, agent): # Configure agent differently based on request data tier = query_params.get('tier', 'standard') agent.set_params({"end_of_speech_timeout": 300 if tier == 'premium' else 500})
self.set_dynamic_config_callback(self.configure_agent_dynamically) ```
# Configure skills with parameters agent.add_skill("web_search", { "num_results": 3, "delay": 0.5 }) ```
class MyCustomSkill(SkillBase): SKILL_NAME = "my_skill" SKILL_DESCRIPTION = "A custom skill" REQUIRED_PACKAGES = ["requests"] REQUIRED_ENV_VARS = ["API_KEY"]
def setup(self) -> bool:
# Initialize the skill
return True
def register_tools(self) -> None:
# Register tools with the agent
self.agent.define_tool(...)
```
The dynamic configuration system enables agents to adapt their behavior on a per-request basis by examining incoming HTTP request data. This architectural pattern supports complex use cases like multi-tenant applications, A/B testing, and personalization while maintaining a single agent deployment.
Dynamic configuration intercepts the SWML document generation process to apply request-specific configuration:
┌─────────────┐ ┌──────────────────┐ ┌─────────────────────┐ ┌──────────────┐
│ HTTP │ │ Dynamic Config │ │ EphemeralAgent │ │ SWML │
│ Request │━━━▶│ Callback │━━━▶│ Config │━━━▶│ Document │
└─────────────┘ └──────────────────┘ └─────────────────────┘ └──────────────┘
│ │ │ │
│ │ │ │
┌───▼────┐ ┌────▼─────┐ ┌─────▼──────┐ ┌────▼────┐
│Query │ │Request │ │Agent │ │Rendered │
│Params │ │Data │ │Builder │ │Response │
│Body │ │Analysis │ │Methods │ │ │
│Headers │ │Logic │ │Execution │ │ │
└────────┘ └──────────┘ └────────────┘ └─────────┘
EphemeralAgentConfig object using familiar AgentBase methods┌─────────────────────────────────────────────────────────────────────────────────┐
│ Dynamic Configuration Request Flow │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. HTTP Request arrives (GET/POST /) │
│ │ │
│ 2. Extract request data │ │
│ ┌────────────────────▼────────────────────┐ │
│ │ • Query Parameters (URL params) │ │
│ │ • Body Parameters (POST JSON) │ │
│ │ • Headers (HTTP headers) │ │
│ └────────────────────┬────────────────────┘ │
│ │ │
│ 3. Check for callback │ │
│ ┌────────────────────▼────────────────────┐ │
│ │ if dynamic_config_callback is set: │ │
│ │ - Create EphemeralAgentConfig │ │
│ │ - Call callback with request data │ │
│ │ - Apply ephemeral configuration │ │
│ │ else: │ │
│ │ - Use static agent configuration │ │
│ └────────────────────┬────────────────────┘ │
│ │ │
│ 4. Generate SWML │ │
│ ┌────────────────────▼────────────────────┐ │
│ │ • Render AI verb with configuration │ │
│ │ • Include languages, params, prompts │ │
│ │ • Apply hints and global data │ │
│ │ • Generate function URLs with tokens │ │
│ └────────────────────┬────────────────────┘ │
│ │ │
│ 5. Return SWML Document │ │
│ ┌────────────────────▼────────────────────┐ │
│ │ • Complete SWML with customizations │ │
│ │ • Ready for SignalWire platform │ │
│ └─────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
The EphemeralAgentConfig object provides the same familiar methods as AgentBase but applies them temporarily for a single request:
┌───────────────────────────────────────────────────────────────────────────────┐
│ EphemeralAgentConfig Structure │
├───────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Prompt Sections │ │ Language Config │ │ AI Parameters │ │
│ │ ─────────────── │ │ ─────────────── │ │ ─────────────── │ │
│ │ • add_section() │ │ • add_language()│ │ • set_params() │ │
│ │ • set_prompt() │ │ • voice config │ │ • timeouts │ │
│ │ • post_prompt │ │ • fillers │ │ • volumes │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Global Data │ │ Hints & Speech │ │ Functions │ │
│ │ ─────────────── │ │ ─────────────── │ │ ─────────────── │ │
│ │ • set_global() │ │ • add_hints() │ │ • native_funcs()│ │
│ │ • update_data() │ │ • pronunciation │ │ • recognition │ │
│ │ • session data │ │ • recognition │ │ • external URLs │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────────┘
The dynamic configuration system is designed with performance in mind:
Request 1 ┌─────────────┐ Request 2 ┌─────────────┐ Request 3 ┌─────────────┐
Lifecycle │ CREATE │ Lifecycle │ CREATE │ Lifecycle │ CREATE │
│ EphemeralCfg│ │ EphemeralCfg│ │ EphemeralCfg│
│ ↓ │ │ ↓ │ │ ↓ │
│ CONFIGURE │ │ CONFIGURE │ │ CONFIGURE │
│ ↓ │ │ ↓ │ │ ↓ │
│ RENDER SWML │ │ RENDER SWML │ │ RENDER SWML │
│ ↓ │ │ ↓ │ │ ↓ │
│ DESTROY │ │ DESTROY │ │ DESTROY │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
▼ ▼ ▼
Garbage Garbage Garbage
Collection Collection Collection
The dynamic configuration architecture supports several key patterns:
┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ Tenant B │ │ Same Agent │ │ Config B │ │ Request │━━━▶│ Instance │━━━▶│ Applied │ └─────────────┘ └──────────────┘ └─────────────┘ ```
┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ Test │ │ Decision │ │ Version B │ │ Group │━━━▶│ Logic │━━━▶│ Config │ └─────────────┘ └──────────────┘ └─────────────┘ ```
┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ MX Request │ │ Locale │ │ Spanish │ │ (es-MX) │━━━▶│ Detection │━━━▶│ Voice + MXN │ └─────────────┘ └──────────────┘ └─────────────┘ ```
Dynamic configuration integrates with other SDK components:
The system includes robust error handling:
def configure_agent_dynamically(self, query_params, body_params, headers, agent):
try:
# Primary configuration logic
self.apply_custom_config(query_params, agent)
except ConfigurationError as e:
# Log error and apply safe defaults
self.log.error("dynamic_config_error", error=str(e))
self.apply_default_config(agent)
except Exception as e:
# Catch-all with minimal safe configuration
self.log.error("dynamic_config_critical", error=str(e))
agent.add_language("English", "en-US", "rime.spore:mistv2")
The architecture supports gradual migration from static to dynamic configuration:
This approach ensures zero downtime and allows for testing and validation at each phase.
The SDK includes a collection of prefab agents that provide ready-to-use implementations for common use cases. These prefabs can be used directly or serve as templates for custom implementations.
Use cases: Form filling, survey collection, intake processes
FAQBotAgent
Use cases: FAQ bots, documentation assistants, support agents
ConciergeAgent
Use cases: Front-desk services, triage systems, switchboard operators
SurveyAgent
Use cases: Customer satisfaction surveys, feedback collection, market research
ReceptionistAgent
Users can create their own prefab agents by extending AgentBase or any existing prefab. Custom prefabs can be created within your project or packaged as reusable libraries.
Key steps for creating custom prefabs:
Extend the base class:
python
class MyCustomPrefab(AgentBase):
def __init__(self, custom_param, **kwargs):
super().__init__(**kwargs)
self._custom_param = custom_param
Configure defaults: ```python # Set standard prompt sections self.prompt_add_section("Personality", body="I am a specialized agent for...") self.prompt_add_section("Goal", body="Help users with...")
# Add default tools self.register_default_tools() ```
Add specialized tools:
python
@AgentBase.tool(
name="specialized_function",
description="Do something specialized",
parameters={...}
)
def specialized_function(self, args, raw_data):
# Implementation
return SwaigFunctionResult("Function result")
Create a factory method (optional):
python
@classmethod
def create(cls, config_dict, **kwargs):
"""Create an instance from a configuration dictionary"""
return cls(
custom_param=config_dict.get("custom_param", "default"),
name=config_dict.get("name", "custom_prefab"),
**kwargs
)
When designing prefabs, consider exposing these customization points:
The POM (Prompt Object Model) represents a structured approach to prompt construction:
┌───────────────────────────────────────────────┐
│ Prompt │
├───────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────────┐ │
│ │ Personality │ │ Goal │ │
│ └─────────────────┘ └─────────────────────┘ │
│ ┌─────────────────┐ ┌─────────────────────┐ │
│ │ Instructions │ │ Hints │ │
│ └─────────────────┘ └─────────────────────┘ │
│ ┌─────────────────┐ ┌─────────────────────┐ │
│ │ Languages │ │ Custom Sections │ │
│ └─────────────────┘ └─────────────────────┘ │
└───────────────────────────────────────────────┘
The Contexts and Steps system provides an alternative to traditional POM prompts for building structured, workflow-driven AI interactions. This system represents a fundamental shift from unstructured conversation to guided workflow execution.
┌─────────────────────────────────────────────────────────────┐
│ ContextBuilder │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
│ │ Context A │ │ Context B │ │ Context C │ │
│ │ ┌─────────────┐ │ │ ┌─────────────┐ │ │ ┌─────────┐ │ │
│ │ │ Step 1 │ │ │ │ Step 1 │ │ │ │ Step 1 │ │ │
│ │ │ - Content │ │ │ │ - Content │ │ │ │ - Content│ │ │
│ │ │ - Criteria │ │ │ │ - Criteria │ │ │ │ - Criteria│ │ │
│ │ │ - Functions │ │ │ │ - Functions │ │ │ │ - Functions│ │ │
│ │ │ - Navigation│ │ │ │ - Navigation│ │ │ │ - Navigation│ │ │
│ │ └─────────────┘ │ │ └─────────────┘ │ │ └─────────┘ │ │
│ │ ┌─────────────┐ │ │ ┌─────────────┐ │ │ │ │ │
│ │ │ Step 2 │ │ │ │ Step 2 │ │ │ │ │ │
│ │ └─────────────┘ │ │ └─────────────┘ │ │ │ │ │
│ └─────────────────┘ └─────────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
The system implements sophisticated navigation control through two primary mechanisms:
Intra-Context Navigation (Steps within a Context):
Context: Customer Service
┌────────────┐ valid_steps ┌──────────────┐ valid_steps ┌──────────────┐
│ greeting │ ────────────────▶ │ identify │ ────────────────▶ │ resolve │
└────────────┘ └──────────────┘ └──────────────┘
│ │ │
│ valid_steps = ["identify"] │ valid_steps = ["resolve", "escalate"] │
└───────────────────────────────┘ │
│
┌──────────────┐ ◀────────────────────┘
│ escalate │ valid_steps = ["escalate"]
└──────────────┘
Inter-Context Navigation (Switching between Contexts):
┌─────────────────┐ valid_contexts ┌─────────────────┐ valid_contexts ┌─────────────────┐
│ Triage │ ─────────────────▶ │ Technical │ ─────────────────▶ │ Billing │
│ │ │ Support │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
│ valid_contexts = ["technical", "billing", "general"] │ │
└────────────────────────────────────────────────────────────┘ │
│
┌─────────────────┐ ◀──────────────────────────────────────────────────────────────┘
│ General │ valid_contexts = ["triage"]
│ Inquiries │
└─────────────────┘
Each step can restrict available AI functions to enhance security and user experience:
┌─────────────────────────────────────────────────┐
│ Function Access Control by Step │
├─────────────────────────────────────────────────┤
│ │
│ Public Context │
│ ┌─────────────────┐ │
│ │ Initial Contact │ Functions: ["datetime"] │
│ └─────────────────┘ │
│ │
│ Authenticated Context │
│ ┌─────────────────┐ │
│ │ User Verified │ Functions: ["datetime", │
│ └─────────────────┘ "web_search"] │
│ │
│ Sensitive Context │
│ ┌─────────────────┐ │
│ │ Account Access │ Functions: "none" │
│ └─────────────────┘ │
└─────────────────────────────────────────────────┘
The contexts system integrates with the existing SWML generation pipeline:
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ ContextBuilder │ ───▶ │ Context Data │ ───▶ │ SWML AI Verb │
│ │ │ Serialization │ │ Generation │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
│ │ ▼
│ │ ┌─────────────────┐
│ │ │ prompt: { │
│ │ │ contexts: { │
│ │ │ "context1": │
│ │ │ steps: {} │
│ │ │ } │
│ │ │ } │
│ │ └─────────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Step Content │ │ Navigation │
│ - Text/POM │ │ - valid_steps │
│ - Functions │ │ - valid_contexts│
│ - Criteria │ │ - Restrictions │
└─────────────────┘ └─────────────────┘
Coexistence with Traditional Prompts:
┌─────────────────────────────────────────────────┐
│ Agent Configuration │
├─────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────────┐ │
│ │ Traditional │ │ Contexts and │ │
│ │ POM Sections │ │ Steps Workflow │ │
│ │ (from skills, │ │ │ │
│ │ global config) │ │ │ │
│ └─────────────────┘ └─────────────────────┘ │
│ │ │ │
│ └───────────┬───────────┘ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Combined SWML │ │
│ │ Output │ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────┘
Skills and Function Integration:
Context Validation Rules:
Step Content Rules:
set_text() with add_section() in same stepNavigation Validation:
valid_steps must exist in same contextvalid_contexts must exist in agentFunction Security:
set_functions() allows all functionsMemory Usage:
Execution Flow:
Scalability:
Use Contexts and Steps when:
Use DataMap when:
Use Skills when:
Use Custom Tools when:
The architecture supports using all these approaches together, allowing developers to choose the right tool for each specific requirement within a single agent.
Functions are defined with: - Name - Description - Parameters schema - Implementation - Security settings
Example:
@AgentBase.tool(
name="get_weather",
description="Get the current weather for a location",
parameters={
"location": {
"type": "string",
"description": "The city or location to get weather for"
}
}
)
def get_weather(self, args, raw_data):
location = args.get("location", "Unknown location")
return SwaigFunctionResult(f"It's sunny and 72°F in {location}.")
The SDK uses FastAPI for routing with these key endpoints:
The SDK also supports dynamic creation of custom routing endpoints:
/customer, /product)The SDK supports multiple deployment models:
Direct invocation via agent.run() (auto-detects deployment mode)
Multi-Agent Mode
app.include_router(agent.as_router(), prefix=agent.route)
Reverse Proxy Integration
SWML_PROXY_URL_BASE for proper webhook URL generationEnable SSL termination at proxy level
Direct HTTPS Mode
agent.serve(ssl_cert="cert.pem", ssl_key="key.pem")Use specific instructions for behavior guidance
SWAIG Functions
Return structured responses
State Management
enable_state_tracking=TrueUse secure state storage for sensitive data
Security
Enable security for sensitive operations with secure=True
Deployment
Monitor agent performance and usage
Prefab Usage
The SDK uses JSON Schema validation for: - SWML document structure - POM section validation - SWAIG function parameter validation
Schema definitions are loaded from the schema.json file, which provides the complete specification for all supported SWML verbs and structures.
The SDK uses structlog for structured logging with JSON output format. Key events logged include: - Service initialization - Request handling - Function execution - Authentication events - Error conditions
Configuration options are available through: 1. Constructor Parameters: Direct configuration in code 2. Environment Variables: System-level configuration 3. Method Calls: Runtime configuration updates
Key environment variables:
- SWML_BASIC_AUTH_USER: Username for basic auth
- SWML_BASIC_AUTH_PASSWORD: Password for basic auth
- SWML_PROXY_URL_BASE: Base URL when behind reverse proxy
- SWML_SSL_ENABLED: Enable HTTPS
- SWML_SSL_CERT_PATH: Path to SSL certificate
- SWML_SSL_KEY_PATH: Path to SSL key
- SWML_DOMAIN: Domain name for the service
- SWML_SCHEMA_PATH: Optional path to override the schema.json location
on_swml_request() is called to allow customizationon_summary() is called to process the dataThe SDK provides a flexible state management system:
┌───────────────┐ ┌─────────────────┐ ┌───────────────┐
│ Session │ │ State │ │ Persistence │
│ Management │━━━━▶│ Manager │━━━━▶│ Layer │
└───────────────┘ └─────────────────┘ └───────────────┘
Components: - SessionManager: Handles session creation, activation, and termination - StateManager: Interface for state operations - Implementation Options: FileStateManager, MemoryStateManager, etc.
State is indexed by call ID and can store arbitrary JSON data. When enable_state_tracking=True is set, the system automatically registers lifecycle hooks:
- startup_hook: Called when a new call/session starts
- hangup_hook: Called when a call/session ends
Common state management methods:
- get_state(call_id): Retrieve state for a call
- update_state(call_id, data): Update state for a call
- set_state(call_id, data): Set state for a call (overriding existing)
- clear_state(call_id): Remove state for a call