signalwire-agents 1.1.0

SignalWire AI Agents SDK

Agents SDK

A Python SDK for creating, hosting, and securing SignalWire AI agents as microservices.

Documentation · Report an Issue · PyPI

---

Quick Start

pip install signalwire-agents

from signalwire_agents import AgentBase
from signalwire_agents.core.function_result import SwaigFunctionResult

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("Get the current time")
    def get_time(self):
        """Get the current time"""
        from datetime import datetime
        return SwaigFunctionResult(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

Features

• Self-contained agents -- each agent is both a web application and an AI persona
• Prompt Object Model (POM) -- structured prompt composition via prompt_add_section()
• SWAIG tools -- SWAIG (SignalWire AI Gateway) is the platform's AI tool-calling system with native access to the media stack; define functions with @AgentBase.tool() decorators and the AI can invoke them mid-call
• Skills system -- add capabilities with one-liners: agent.add_skill("datetime")
• Contexts and steps -- structured multi-step workflows with navigation control
• DataMap tools -- define tools that execute on SignalWire's servers, calling REST APIs without needing your own webhook endpoints
• 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 tokens, SSL support
• Serverless deployment -- auto-detects Lambda, CGI, Google Cloud Functions, Azure Functions

Installation

# Core SDK
pip install signalwire-agents

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

Examples

The examples/ directory contains 50+ working examples. A few starting points:

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, SwaigFunctionResult actions
session_and_state_demo.py	on_summary, global data, post-prompt summaries
swaig_features_agent.py	Type inference, fillers, default webhook URLs
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.

Run any example:

python examples/simple_agent.py

# Or test without running a server
swaig-test examples/simple_agent.py --list-tools
swaig-test examples/simple_agent.py --dump-swml
swaig-test examples/simple_agent.py --exec get_weather --location "New York"

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_agents.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.

REST Client

Synchronous REST client for managing SignalWire resources and controlling calls over HTTP. No WebSocket required.

from signalwire_agents.rest import SignalWireClient

client = SignalWireClient(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")

• Namespaced sub-objects for every API: Fabric (13 resource types), Calling (37 commands), Video, Datasphere, Compat (Twilio-compatible), 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.

Documentation

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

Guides are also available in the docs/ directory:

Getting Started

• Agent Guide -- creating agents, prompt configuration, dynamic setup
• Architecture -- SDK architecture and core concepts
• SDK Features -- feature overview, SDK vs raw SWML (SignalWire Markup Language) 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 (the JSON format that defines agent behavior during calls)

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

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

Environment Variables

Variable	Description
SWML_BASIC_AUTH_USER	Basic auth username (default: auto-generated)
SWML_BASIC_AUTH_PASSWORD	Basic auth password (default: auto-generated)
SWML_PROXY_URL_BASE	Base URL when behind a reverse proxy
SWML_SSL_ENABLED	Enable HTTPS (true, 1, yes)
SWML_SSL_CERT_PATH	Path to SSL certificate
SWML_SSL_KEY_PATH	Path to SSL private key
SWML_DOMAIN	Domain for SSL and external URLs

Testing

# 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_agents --cov-report=html

License

MIT -- see LICENSE for details.