SWMLService
SWMLService is the foundation class for creating and serving SWML (SignalWire Markup
Language) documents. It provides SWML document generation with schema validation,
a built-in FastAPI web server for serving documents over HTTP, and basic authentication
for securing endpoints. Most developers will use
AgentBase (which extends SWMLService)
rather than working with SWMLService directly. Use SWMLService when you need
low-level control over SWML document construction without the AI agent abstractions.
AgentBase extends SWMLService — it
inherits all document generation, serving, and authentication capabilities documented here.
SWMLService generates and serves SWML documents over HTTP. See the SWML reference for the full document specification.
Properties
name
Service name/identifier used in logging and server startup messages.
route
HTTP route path where this service is accessible. Trailing slashes are stripped automatically during initialization.
host
Host address the web server binds to.
port
Port number the web server binds to.
schema_utils
Schema validation utilities for SWML documents. Provides verb validation, verb name enumeration, and schema property lookups.
verb_registry
Registry of specialized verb handlers. Manages custom handlers for complex SWML
verbs that require logic beyond generic schema validation (e.g., the ai verb).
log
Structured logger instance bound to this service name.
security
Unified security configuration loaded from environment variables and optional config file. Controls SSL, CORS, and host allowlist settings.
ssl_enabled
Whether SSL/HTTPS is enabled. Mirrors security.ssl_enabled for backward compatibility.
ssl_cert_path
Path to the SSL certificate file. Mirrors security.ssl_cert_path for backward compatibility.
ssl_key_path
Path to the SSL private key file. Mirrors security.ssl_key_path for backward compatibility.
domain
Domain name for SSL certificates. Mirrors security.domain for backward compatibility.
full_validation_enabled
Read-only property indicating whether full JSON Schema validation is active.
Controlled by the schema_validation property or the
SWML_SKIP_SCHEMA_VALIDATION environment variable.
The constructor also accepts basic_auth, schema_path, config_file, and
schema_validation parameters. These are not exposed as public instance attributes
after initialization. Use get_basic_auth_credentials() to retrieve auth credentials
and full_validation_enabled to check validation status.
Methods
Add a new empty section to the SWML document.
Add a SWML verb to the main section of the document.
Add a SWML verb to a specific named section of the document.
Create a FastAPI APIRouter for mounting the service into an existing application.
Retrieve the HTTP Basic Auth credentials for the service.
Get the current SWML document as a Python dictionary.
Manually set the proxy URL base for webhook callback generation.
Request handling hook for customizing SWML output per request.
Static utility to extract the SIP username from request body data.
Register routing callbacks for dynamic request handling and SIP routing.
Register custom verb handlers for specialized SWML verb processing.
Render the current SWML document as a JSON string.
Reset the SWML document to an empty state.
Start the FastAPI/Uvicorn web server for the SWML service.
Set the internal running flag to False.
