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"

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.