Agents SDK

$
pip install signalwire-agents

What You’ll Learn

This chapter walks you through the complete setup process:

1. Introduction - Understand what the SDK does and key concepts
2. Installation - Install the SDK and verify it works
3. Quick Start - Build your first agent in under 5 minutes
4. Development Environment - Set up a professional development workflow
5. Exposing Your Agent - Make your agent accessible to SignalWire using ngrok

Prerequisites

Before starting, ensure you have:

• Python 3.8 or higher installed on your system
• pip (Python package manager)
• A terminal/command line interface
• A text editor or IDE (VS Code, PyCharm, etc.)
• (Optional) A SignalWire account for testing with real phone calls

Time to Complete

By the End of This Chapter

You will have:

• A working voice AI agent
• Accessible via public URL
• Ready to connect to SignalWire phone numbers

What is the SignalWire Agents SDK?

The SignalWire Agents SDK lets you create voice AI agents - intelligent phone-based assistants that can:

• Answer incoming phone calls automatically
• Have natural conversations using AI (GPT-4, Claude, etc.)
• Execute custom functions (check databases, call APIs, etc.)
• Transfer calls, play audio, and manage complex call flows
• Scale from development to production seamlessly

How It Works

The flow:

1. A caller dials your SignalWire phone number
2. SignalWire requests instructions from your agent (via HTTP)
3. Your agent returns SWML (SignalWire Markup Language) - a JSON document describing how to handle the call
4. SignalWire’s AI talks to the caller based on your configuration
5. When the AI needs to perform actions, it calls your SWAIG functions (webhooks)
6. Your functions return results, and the AI continues the conversation

Key Concepts

Agent

An Agent is your voice AI application. It’s a Python class that:

• Defines the AI’s personality and behavior (via prompts)
• Provides functions the AI can call (SWAIG functions)
• Configures voice, language, and AI parameters
• Runs as a web server that responds to SignalWire requests

1
from signalwire_agents import AgentBase
2
3
4
class MyAgent(AgentBase):
5
    def __init__(self):
6
        super().__init__(name="my-agent")
7
        # Configure your agent here

SWML (SignalWire Markup Language)

SWML is a JSON format that tells SignalWire how to handle calls. Your agent generates SWML automatically - you don’t write it by hand.

1
{
2
  "version": "1.0.0",
3
  "sections": {
4
    "main": [
5
      {"answer": {}},
6
      {"ai": {
7
        "prompt": {"text": "You are a helpful assistant..."},
8
        "SWAIG": {"functions": [...]}
9
      }}
10
    ]
11
  }
12
}

SWAIG Functions

SWAIG (SignalWire AI Gateway) functions are tools your AI can use during a conversation. When a caller asks something that requires action, the AI calls your function.

1
@agent.tool(description="Look up a customer by phone number")
2
def lookup_customer(args: dict, raw_data: dict = None) -> SwaigFunctionResult:
3
    phone_number = args.get("phone_number", "")
4
    customer = database.find(phone_number)
5
    return SwaigFunctionResult(f"Customer: {customer.name}, Account: {customer.id}")

Skills

Skills are reusable plugins that add capabilities to your agent. The SDK includes built-in skills for common tasks:

• datetime - Get current time and date
• web_search - Search the web
• weather_api - Get weather information
• math - Perform calculations

1
agent.add_skill("datetime")
2
agent.add_skill("web_search", google_api_key="...")

What You Can Build

The SDK includes prefab agents for common scenarios (InfoGatherer, FAQBot, Survey, Receptionist) that you can customize or use as starting points.

SDK Features

Minimal Example

Here’s the simplest possible agent:

1
from signalwire_agents import AgentBase
2
3
4
class HelloAgent(AgentBase):
5
    def __init__(self):
6
        super().__init__(name="hello")
7
        self.prompt_add_section("Role", "You are a friendly assistant.")
8
9
10
if __name__ == "__main__":
11
    agent = HelloAgent()
12
    agent.run()

This agent:

• Starts a web server on port 3000
• Returns SWML that configures an AI assistant
• Uses the default voice and language settings
• Has no custom functions (just conversation)

Next Steps

Now that you understand what the SDK does, let’s install it and build something real.