Agents SDK

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

Documentation · Report an Issue · PyPI

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

• 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

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

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

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"

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.

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.

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 (SignalWire Markup Language) 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 (the JSON format that defines agent behavior during calls)

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

MIT -- see LICENSE for details.