signalwire-agents-sdk

SignalWire AI Agents SDK Expert

You are an expert in the SignalWire AI Agents SDK for Python. You help developers build production-ready voice AI agents using SWML (SignalWire Markup Language) and SWAIG (SignalWire AI Gateway).

When This Skill Applies

Activate this skill when the user:

• Imports from signalwire_agents or signalwire_agents.core
• Creates classes extending AgentBase
• Works with SWAIG functions, tools, or handlers
• Configures voice, language, or TTS settings
• Uses DataMap for server-side functions
• Works with agent skills (built-in or custom)
• Asks about SWML, prompts, or call flow
• Deploys agents (serverless, Docker, multi-agent)

Core SDK Knowledge

Package Structure

# Main imports
from signalwire_agents import AgentBase
from signalwire_agents.core.function_result import SwaigFunctionResult
from signalwire_agents.core.data_map import DataMap

# For multi-agent deployments
from signalwire_agents import AgentServer

# For custom skills
from signalwire_agents.core.skill_base import SkillBase

# For workflows
from signalwire_agents.core.contexts import Context, Step, ContextBuilder

AgentBase - The Foundation

AgentBase is the main class for building agents. It combines multiple mixins:

• PromptMixin: Prompt building (prompt_add_section, POM)
• ToolMixin: SWAIG functions (define_tool, @tool)
• SkillMixin: Skill management (add_skill, remove_skill)
• AIConfigMixin: Voice, language, hints, parameters
• WebMixin: HTTP endpoints and routing
• AuthMixin: Basic auth, token security
• StateMixin: Conversation state
• ServerlessMixin: Lambda/Cloud Functions support

Constructor Parameters:

Parameter	Type	Default	Description
name	str	required	Agent identifier
route	str	"/"	HTTP endpoint path
host	str	"0.0.0.0"	Server bind address
port	int	3000	Server port
basic_auth	tuple	None	(username, password) for HTTP auth
auto_answer	bool	True	Automatically answer calls
record_call	bool	False	Enable call recording
record_format	str	"mp4"	Recording format
record_stereo	bool	True	Stereo recording

SWAIG Function Definition

Method 1: @tool Decorator (Recommended)

@AgentBase.tool(
    name="function_name",
    description="Clear description for the AI to understand when to call this",
    parameters={
        "param_name": {
            "type": "string",
            "description": "What this parameter represents"
        },
        "optional_param": {
            "type": "integer",
            "description": "Optional parameter",
            "default": 10
        }
    }
)
def function_name(self, args, raw_data):
    param = args.get("param_name")
    return SwaigFunctionResult(f"Result for {param}")

Method 2: define_tool() (Imperative)

def __init__(self):
    super().__init__(name="my-agent")

    self.define_tool(
        name="lookup_order",
        description="Look up an order by ID",
        parameters={
            "order_id": {
                "type": "string",
                "description": "The order ID to look up"
            }
        },
        handler=self.handle_lookup_order
    )

def handle_lookup_order(self, args, raw_data):
    order_id = args.get("order_id")
    # ... lookup logic
    return SwaigFunctionResult(f"Order {order_id} status: shipped")

Handler Signature:

def handler(self, args: dict, raw_data: dict) -> SwaigFunctionResult:
    # args: Parameters passed by the AI
    # raw_data: Full request including call_id, metadata, etc.
    pass

SwaigFunctionResult

The return type for all SWAIG function handlers.

from signalwire_agents.core.function_result import SwaigFunctionResult

# Simple response
return SwaigFunctionResult("The weather is sunny and 72°F")

# Response with action
return SwaigFunctionResult("Transferring you now").add_action(
    "transfer", {"dest": "tel:+15551234567"}
)

# Multiple actions (method chaining)
return (SwaigFunctionResult("Let me play some music while I transfer you")
    .add_action("play", {"url": "https://example.com/hold.mp3"})
    .add_action("transfer", {"dest": "sip:[email protected]"}))

# Post-process (AI responds before actions execute)
return SwaigFunctionResult("I'll transfer you to support", post_process=True).add_action(
    "transfer", {"dest": "tel:+15559876543"}
)

Common Actions:

Action	Parameters	Description
transfer	dest	Transfer call to destination
hangup	reason	End the call
play	url, urls	Play audio file(s)
set_global_data	key-value pairs	Update conversation data
toggle_functions	active, inactive	Enable/disable functions
playback_bg	file, wait	Background audio
stop_playback_bg	-	Stop background audio

Voice and Language Configuration

# Add a language with voice
self.add_language("English", "en-US", "rime.spore")

# Multiple languages
self.add_language("English", "en-US", "rime.spore")
self.add_language("Spanish", "es-MX", "rime.spore")

# Available TTS engines and example voices:
# - ElevenLabs: "elevenlabs.josh", "elevenlabs.rachel"
# - Google: "gcloud.en-US-Neural2-A"
# - Azure: "azure.en-US-JennyNeural"
# - Amazon: "polly.Matthew"
# - Cartesia: "cartesia.default"
# - Deepgram: "deepgram.aura-asteria-en"
# - OpenAI: "openai.nova"
# - Rime (default): "rime.spore", "rime.marsh"

Prompt Building

Method 1: prompt_add_section()

# Simple section
self.prompt_add_section("Role", "You are a helpful customer service agent.")

# Section with bullets
self.prompt_add_section(
    "Guidelines",
    body="Follow these rules:",
    bullets=[
        "Be friendly and professional",
        "Keep responses concise",
        "Ask clarifying questions when needed"
    ]
)

# Subsection
self.prompt_add_subsection(
    "Guidelines",
    "Escalation",
    body="Transfer to a human if the customer asks."
)

Method 2: Declarative PROMPT_SECTIONS

class MyAgent(AgentBase):
    PROMPT_SECTIONS = {
        "Role": "You are a helpful assistant.",
        "Guidelines": [
            "Be concise",
            "Be accurate",
            "Be helpful"
        ],
        "Personality": {
            "body": "You have a friendly demeanor.",
            "bullets": ["Use casual language", "Add appropriate humor"]
        }
    }

AI Parameters

self.set_params({
    # Speech detection
    "end_of_speech_timeout": 1000,      # ms of silence to end turn
    "attention_timeout": 10000,          # ms before "are you there?"
    "inactivity_timeout": 300000,        # ms before hanging up

    # Interruption handling
    "barge_match_string": "stop|cancel|help",
    "barge_min_words": 2,

    # AI behavior
    "ai_volume": 0,                       # -50 to 50 dB adjustment
    "local_tz": "America/New_York",

    # Energy detection
    "energy_threshold": 0.05             # 0.01-1.0, lower = more sensitive
})

Speech Recognition Hints

# Add hints for better recognition
self.add_hints(["SignalWire", "SWML", "SWAIG", "API"])

# Industry-specific hints
self.add_hints([
    "account number",
    "routing number",
    "checking",
    "savings"
])

Call Flow Customization

Control what happens before/after the AI conversation:

# Pre-answer: Play ringback while call rings
self.add_pre_answer_verb("play", {
    "urls": ["ring:us"],
    "auto_answer": False  # Required for pre-answer
})

# Post-answer: Welcome message before AI
self.add_post_answer_verb("play", {
    "url": "say:Thank you for calling. This call may be recorded."
})
self.add_post_answer_verb("sleep", {"time": 500})

# Post-AI: Cleanup after conversation ends
self.add_post_ai_verb("request", {
    "url": "https://api.example.com/call-complete",
    "method": "POST"
})
self.add_post_ai_verb("hangup", {})

Pre-answer safe verbs: transfer, execute, return, label, goto, request, switch, cond, if, eval, set, unset, hangup, send_sms, sleep

Skills System

Adding Built-in Skills:

# Web search
self.add_skill("web_search", {
    "api_key": "your-google-api-key",
    "search_engine_id": "your-cse-id"
})

# Weather
self.add_skill("weather_api", {
    "provider": "openweathermap",
    "api_key": "your-api-key",
    "units": "imperial"
})

# Date/time
self.add_skill("datetime", {"timezone": "America/New_York"})

# Math operations
self.add_skill("math")

Available Built-in Skills:

• web_search - Google Custom Search
• wikipedia_search - Wikipedia lookups
• weather_api - Weather data
• math - Mathematical operations
• datetime - Date/time functions
• native_vector_search - Local document search
• swml_transfer - Call transfers
• datasphere - Data integration

DataMap (Server-Side Functions)

For functions that don't need local handlers:

from signalwire_agents.core.data_map import DataMap

weather_func = (DataMap("get_weather")
    .purpose("Get current weather for a location")
    .parameter("city", "string", "City name", required=True)
    .webhook("GET", "https://api.weather.com/v1/current?q=${args.city}&key=KEY")
    .output(SwaigFunctionResult(
        "The weather in ${args.city} is ${response.condition} "
        "and ${response.temp_f}°F"
    ))
)

self.register_swaig_function(weather_func.to_swaig_function())

Multi-Agent Deployment

from signalwire_agents import AgentServer

server = AgentServer(host="0.0.0.0", port=3000)

server.register(SupportAgent(), "/support")
server.register(SalesAgent(), "/sales")
server.register(FAQAgent(), "/faq")

# Optionally serve static files (web UI)
server.serve_static_files("./web")

server.run()

Environment Variables

Common envi

---

Content truncated.