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

pip install signalwire

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) -- your agent just 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()

Test 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

• Prompt Object Model (POM) -- structured prompt composition via prompt_add_section()
• SWAIG tools -- define functions with @AgentBase.tool() that the AI calls mid-conversation, with native access to the call's media stack
• Skills system -- add capabilities with one-liners: agent.add_skill("datetime")
• Contexts and steps -- structured multi-step workflows with navigation control
• DataMap tools -- tools that execute 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 -- serve multiple agents on a single server with AgentServer
• Local search -- offline document search with vector similarity and keyword matching
• SIP routing -- route SIP calls to agents based on usernames
• Session state -- persistent conversation state with global data and post-prompt summaries
• Security -- auto-generated basic auth, function-specific HMAC tokens, SSL support
• Serverless -- auto-detects Lambda, CGI, Google Cloud Functions, Azure Functions

The examples/ directory contains 50+ working examples:

See examples/README.md for the full list organized by category.

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()

• 57+ calling methods (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.

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", "text": "Hello!"}])
client.phone_numbers.search(area_code="512")
client.datasphere.documents.search(query_string="billing policy")

• 21 namespaced API surfaces: Fabric (13 resource types), Calling (37 commands), Video, Datasphere, Compat (Twilio-compatible), Phone Numbers, SIP, Queues, Recordings, and more
• Shared requests.Session for connection pooling
• Dict returns -- raw JSON, no wrapper objects

See the REST documentation for the full guide, API reference, and examples.

# Core SDK (agents, RELAY, REST)
pip install signalwire

# With search (pick one based on your needs)
pip install signalwire[search-queryonly]   # Query pre-built .swsearch files (~400MB)
pip install signalwire[search]              # Build + query search indexes (~500MB)
pip install signalwire[search-full]         # + PDF, DOCX, Excel, HTML processing (~600MB)
pip install signalwire[search-all]          # All search features (~700MB)

Full reference documentation is available at developer.signalwire.com/sdks/agents-sdk.

Guides are also available in the docs/ directory:

• Agent Guide -- creating agents, prompt configuration, dynamic setup
• Architecture -- SDK architecture and core concepts
• SDK Features -- feature overview, SDK vs raw SWML comparison

• 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

• Skills System -- built-in skills and the modular framework
• Third-Party Skills -- creating and publishing custom skills
• MCP Gateway -- Model Context Protocol integration

• 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

• CLI Guide -- swaig-test and sw-search command reference
• Cloud Functions -- Lambda, Cloud Functions, Azure deployment
• Bedrock Agent -- Amazon Bedrock integration
• Configuration -- environment variables, SSL, proxy setup
• Security -- authentication and security model

• API Reference -- complete class and method reference
• Web Service -- HTTP server and endpoint details
• Skills Parameter Schema -- skill parameter definitions

• Multi-Agent Tutorial -- 5-lesson guide from first agent to multi-agent systems
• Fred Bot Tutorial -- build a Wikipedia AI assistant step-by-step

# 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

MIT -- see LICENSE for details.