Pre-release
This release is a pre-release and may not be stable for production use.
SignalWire SDK for Python
Build AI voice agents, control live calls over WebSocket, and manage every SignalWire resource over REST, all from one package.
Documentation · Report an Issue · PyPI
What's in this SDK
| Capability | What it does | Quick link |
|---|---|---|
| AI Agents | Build voice agents that handle calls on their own. The platform runs the AI pipeline, and your code defines the persona, tools, and call flow. | Agent Guide |
| RELAY Client | Control live calls and SMS/MMS in real time over WebSocket: answer, play, record, collect DTMF, conference, transfer, and more | RELAY docs |
| REST Client | Manage SignalWire resources over HTTP: phone numbers, SIP endpoints, Fabric AI agents, video rooms, messaging, and 20 API namespaces | REST docs |
Install the SDK from PyPI:
pip install signalwire-sdk
The package installs its own documentation. sw-pydocs prints a map of the SDK
for the installed version, with the docs, examples and tutorials on disk, and
sw-pydocs api <name> reads signatures from the installed code. If you're a
coding agent working with the SDK, start there:
sw-pydocs # the map: what the SDK does and where to start
sw-pydocs agents # one topic: concepts, files to read, examples, API
sw-pydocs api AgentBase # a signature, docstring and members
AI Agents
Each agent is a self-contained microservice that generates SWML (SignalWire Markup Language) and handles SWAIG (SignalWire AI Gateway) tool calls. The SignalWire platform runs the entire AI pipeline (STT, LLM, TTS), and your agent defines the behavior.
from signalwire import AgentBase
from signalwire.core.function_result import FunctionResult
class MyAgent(AgentBase):
def __init__(self):
super().__init__(name="my-agent", route="/agent")
self.add_language(name="English", code="en-US", voice="inworld.Mark")
self.prompt_add_section("Role", body="You are a helpful assistant.")
@AgentBase.tool(name="get_time")
def get_time(self):
"""Get the current time"""
from datetime import datetime
return FunctionResult(f"The time is {datetime.now().strftime('%H:%M:%S')}")
if __name__ == "__main__":
agent = MyAgent()
agent.run()
swaig-test checks the agent locally, without running a server:
swaig-test my_agent.py --list-tools
swaig-test my_agent.py --dump-swml
swaig-test my_agent.py --exec get_time
Agent Features
An agent built on AgentBase gets these features:
- Prompt Object Model (POM): structured prompt composition with
prompt_add_section() - SWAIG tools: functions defined with
@AgentBase.tool()that the AI calls mid-conversation, with native access to the call's media stack - Skills system: capabilities added in one line, such as
agent.add_skill("datetime") - Contexts and steps: structured multi-step workflows with navigation control
- DataMap tools: tools that run on SignalWire's servers, calling REST APIs without your own webhook
- Dynamic configuration: per-request agent customization for multi-tenant deployments
- Call flow control: pre-answer, post-answer, and post-AI verb insertion
- Prefab agents: ready-to-use archetypes (InfoGatherer, Survey, FAQ, Receptionist, Concierge)
- Multi-agent hosting: multiple agents on a single server with
AgentServer - Local search: offline document search with vector similarity and keyword matching
- SIP routing: SIP calls routed to agents by username
- Session state: persistent conversation state with global data and post-prompt summaries
- Security: auto-generated basic auth, per-call tool tokens, webhook signature validation, and TLS support
- Serverless: automatic detection of Lambda, CGI, Google Cloud Functions, and Azure Functions
Agent Examples
The examples/ directory contains 50+ working examples:
| Example | What it demonstrates |
|---|---|
| simple_agent.py | POM prompts, SWAIG tools, multilingual support, LLM tuning |
| contexts_demo.py | Multi-persona workflow with context switching and step navigation |
| data_map_demo.py | Server-side API tools without webhooks |
| skills_demo.py | Loading built-in skills (datetime, math) |
| call_flow_and_actions_demo.py | Call flow verbs, debug events, FunctionResult actions |
| session_and_state_demo.py | on_summary, global data, post-prompt summaries |
| multi_agent_server.py | Multiple agents on one server |
| lambda_agent.py | AWS Lambda deployment with Mangum |
| comprehensive_dynamic_agent.py | Per-request dynamic configuration, multi-tenant routing |
See examples/README.md for the full list organized by category.
RELAY Client
Real-time call control and messaging over WebSocket. The RELAY client connects to SignalWire via the Blade protocol and gives you imperative, async control over live phone calls and SMS/MMS.
from signalwire.relay import RelayClient
client = RelayClient(
project="...", token="...", host="example.signalwire.com", contexts=["default"]
)
@client.on_call
async def handle(call):
await call.answer()
action = await call.play([{"type": "tts", "params": {"text": "Welcome!"}}])
await action.wait()
await call.hangup()
client.run()
The RELAY client provides:
- Calling methods for play, record, collect, detect, tap, stream, AI, conferencing, and more
- SMS/MMS messaging with delivery tracking
- Action objects with
wait(),stop(),pause(),resume() - Auto-reconnect with exponential backoff
See the RELAY documentation for the full guide, API reference, and examples.
REST Client
Synchronous REST client for managing SignalWire resources and controlling calls over HTTP. No WebSocket required.
from signalwire.rest import RestClient
client = RestClient(project="...", token="...", host="example.signalwire.com")
client.fabric.ai_agents.create(name="Support Bot", prompt={"text": "You are helpful."})
client.calling.play(call_id, play=[{"type": "tts", "params": {"text": "Hello!"}}])
client.phone_numbers.search(areacode="512")
client.datasphere.documents.search(query_string="billing policy")
The REST client provides:
- 20 namespaced API surfaces: Fabric (13 resource types), Calling (37 commands), Video, Datasphere, Phone Numbers, SIP, Queues, Recordings, and more
- A shared
requests.Sessionfor connection pooling - Dict returns: raw JSON, with no wrapper objects
See the REST documentation for the full guide, API reference, and examples.
Installation
The core package covers agents, RELAY and REST. The search extras add local document search; install the one that fits your needs:
# Core SDK (agents, RELAY, REST)
pip install signalwire-sdk
# With search (pick one based on your needs)
pip install "signalwire-sdk[search-queryonly]" # Query pre-built .swsearch files (~400MB)
pip install "signalwire-sdk[search]" # Build + query search indexes (~500MB)
pip install "signalwire-sdk[search-full]" # + PDF, DOCX, Excel, HTML processing (~600MB)
pip install "signalwire-sdk[search-all]" # All search features (~700MB)
Documentation
Full reference documentation is available at signalwire.com/docs/server-sdks.
Guides are also available in the docs/ directory. They're installed with the package, with the examples and tutorials: sw-pydocs path prints where.
Getting Started
- Agent Guide: creating agents, prompt configuration, dynamic setup
- Architecture: SDK architecture and core concepts
- SDK Features: feature overview, SDK vs raw SWML comparison
Core Features
- SWAIG Reference: function results, actions, post_data lifecycle
- Contexts and Steps: structured workflows, navigation, gather mode
- DataMap Guide: serverless API tools without webhooks
- LLM Parameters: temperature, top_p, barge confidence tuning
- SWML Service Guide: low-level construction of SWML documents
- AI Chat Gateway: browser chat widgets without a token in the page
Skills and Extensions
- Skills System: built-in skills and the modular framework
- Third-Party Skills: creating and publishing custom skills
- MCP Gateway: Model Context Protocol integration
Search System
- Search Overview: architecture, installation, quick start
- Search Indexing: building indexes, chunking, embeddings
- Search Integration: agent integration, skills, HTTP API
- Search Deployment: production deployment, pgvector, scaling
Deployment
- CLI Guide:
swaig-testandsw-searchcommand reference - Cloud Functions: Lambda, Cloud Functions, Azure deployment
- Bedrock Agent: Amazon Bedrock integration
- Configuration: environment variables, SSL, proxy setup
- Security: authentication and security model
Reference
- API Reference: complete class and method reference
- Web Service: HTTP server and endpoint details
- Skills Parameter Schema: skill parameter definitions
Tutorials
- Multi-Agent Tutorial: 5-lesson guide from first agent to multi-agent systems
- Fred Bot Tutorial: build a Wikipedia AI assistant step by step
- Full-Guardrails Agent Tutorial: build a reservation line that keeps its rules in code, not in the prompt
Environment Variables
The SDK reads these environment variables:
| Variable | Used by | Description |
|---|---|---|
SIGNALWIRE_PROJECT_ID |
RELAY, REST | Project identifier |
SIGNALWIRE_API_TOKEN |
RELAY, REST | API token |
SIGNALWIRE_SPACE |
RELAY, REST | Space hostname (e.g. example.signalwire.com) |
SWML_BASIC_AUTH_USER |
Agents | Basic auth username (default: auto-generated) |
SWML_BASIC_AUTH_PASSWORD |
Agents | Basic auth password (default: auto-generated) |
SWML_PROXY_URL_BASE |
Agents | Base URL when behind a reverse proxy |
SIGNALWIRE_SIGNING_KEY |
Agents | Your project's signing key. When it's set, agents reject requests SignalWire didn't sign. |
SIGNALWIRE_SWAIG_SECRET |
Agents | Secret for per-call tool tokens. Use the same value on every replica. |
PORT |
Agents | Port the agent listens on (default: 3000) |
SWML_SSL_ENABLED |
Agents | Enable HTTPS (true, 1, yes) |
SWML_SSL_CERT_PATH |
Agents | Path to SSL certificate |
SWML_SSL_KEY_PATH |
Agents | Path to SSL private key |
SIGNALWIRE_LOG_LEVEL |
All | Logging level (debug, info, warning, error, critical) |
SIGNALWIRE_LOG_MODE |
All | Set to off to suppress all logging |
Testing
Run the test suite from the repository root:
# Install dev dependencies
pip install -r requirements-dev.txt
# Run the test suite
pytest
# Run by category
pytest -m unit
pytest -m integration
pytest -m skills
# Coverage
pytest --cov=signalwire --cov-report=html
License
MIT. See LICENSE for details.
1 maintainer
Release files for signalwire-sdk 3.4.3.dev118
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| signalwire_sdk-3.4.3.dev118.tar.gz | 1.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| signalwire_sdk-3.4.3.dev118-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.3 MB
Release files / signalwire_sdk-3.4.3.dev118.tar.gz
| Download URL | signalwire_sdk-3.4.3.dev118.tar.gz |
|---|---|
| Size | 1.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4de0743a96b32dd0700349d047efa7c232ea7c3b6e2c11cf74574d42f55a5108
|
|
BLAKE2b-256 checksum How to use checksums |
50a0509b451c36593e6006cbf68ddb4e0c16cc402f7a94cb8c9db081969b74b2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / signalwire_sdk-3.4.3.dev118-py3-none-any.whl
| Download URL | signalwire_sdk-3.4.3.dev118-py3-none-any.whl |
|---|---|
| Size | 1.8 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4cb89d35422d31e67987f17f34a8a6840dcfc3e2c3540428f93d4c368711dc92
|
|
BLAKE2b-256 checksum How to use checksums |
fc55d36b6320b0ba483757300db2b11fae33831dca7fbd54e6f439d409c5c4c9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
