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.Sessionfor 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-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
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.
2 maintainers
Metadata
2 maintainers
Release files for signalwire-agents 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| signalwire_agents-1.1.0.tar.gz | 488.3 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| signalwire_agents-1.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.1 MB
Release files / signalwire_agents-1.1.0.tar.gz
| Download URL | signalwire_agents-1.1.0.tar.gz |
|---|---|
| Size | 488.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a9ecb5170141d66dbcac30c84e43824417503bf8eb3c37f0a5bb09b0a6cb0bf0
|
|
BLAKE2b-256 checksum How to use checksums |
0262001c77d025b13cc9500fd6b285d350a7fb07fef1ec302c8f9aed2e897870
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.15
|
Release files / signalwire_agents-1.1.0-py3-none-any.whl
| Download URL | signalwire_agents-1.1.0-py3-none-any.whl |
|---|---|
| Size | 583.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4148e2806991ddf5f72e8740447cc59dfe821a65efe4f0505629f45b4b9e4955
|
|
BLAKE2b-256 checksum How to use checksums |
09f6972079b8cd1507cefa4a0736d94d7aa94ad327f0c79930bd0c0ab1dbb68e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.15
|
Security for signalwire-agents 1.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
