Skip to main content

Reference

Summary: Complete API reference for all SignalWire Agents SDK classes, methods, CLI tools, and configuration options.

This chapter provides detailed reference documentation for the SignalWire Agents SDK.

Reference Overview​

API Reference​

  • AgentBase - Main agent class with all methods
  • SWMLService - Base service for SWML generation
  • SwaigFunctionResult - Function return values and actions
  • DataMap - Serverless REST API integration
  • SkillBase - Custom skill development
  • ContextBuilder - Multi-step workflows

CLI Tools​

  • swaig-test - Test agents and functions locally
  • sw-search - Build and query search indexes
  • sw-agent-init - Create new agent projects

Configuration​

  • Environment Variables - Runtime configuration
  • Config Files - YAML/JSON configuration
  • SWML Schema - Document structure reference

Quick Reference​

Creating an Agent​

agent = AgentBase(name="my-agent", route="/agent")
agent.add_language("English", "en-US", "rime.spore")
agent.prompt_add_section("Role", "You are a helpful assistant.")
agent.run()

Defining a Function​

@agent.tool(description="Search for information")
def search(query: str) -> SwaigFunctionResult:
    return SwaigFunctionResult(f"Found results for: {query}")

Returning Actions​

return SwaigFunctionResult("Transferring...").connect("+15551234567")
return SwaigFunctionResult("Goodbye").hangup()
return SwaigFunctionResult().update_global_data({"key": "value"})

Import Patterns​

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

# Prefab agents
from signalwire_agents.prefabs import (
    InfoGathererAgent,
    FAQBotAgent,
    SurveyAgent,
    ReceptionistAgent,
    ConciergeAgent
)

# Context/workflow system
from signalwire_agents.core.contexts import ContextBuilder

# Skill development
from signalwire_agents.core.skill_base import SkillBase

Chapter Contents​

SectionDescription
AgentBase APIMain agent class reference
SWMLService APIBase service class reference
SWAIG Function APIFunction definition reference
SwaigFunctionResult APIReturn value and actions reference
DataMap APIServerless API integration reference
SkillBase APICustom skill development reference
ContextBuilder APIWorkflow system reference
swaig-test CLITesting tool reference
Environment VariablesEnvironment configuration
Config FilesFile-based configuration
SWML SchemaDocument structure reference

Class Definition​

from signalwire_agents import AgentBase

class AgentBase(
    AuthMixin,
    WebMixin,
    SWMLService,
    PromptMixin,
    ToolMixin,
    SkillMixin,
    AIConfigMixin,
    ServerlessMixin,
    StateMixin
)

Constructor​

AgentBase(
    name: str,                              # Agent name/identifier (required)
    route: str = "/",                       # HTTP route path
    host: str = "0.0.0.0",                  # Host to bind
    port: int = 3000,                       # Port to bind
    basic_auth: Optional[Tuple[str, str]] = None,  # (username, password)
    use_pom: bool = True,                   # Use POM for prompts
    token_expiry_secs: int = 3600,          # Token expiration time
    auto_answer: bool = True,               # Auto-answer calls
    record_call: bool = False,              # Enable recording
    record_format: str = "mp4",             # Recording format
    record_stereo: bool = True,             # Stereo recording
    default_webhook_url: Optional[str] = None,  # Default webhook URL
    agent_id: Optional[str] = None,         # Unique agent ID
    native_functions: Optional[List[str]] = None,  # Native function list
    schema_path: Optional[str] = None,      # SWML schema path
    suppress_logs: bool = False,            # Suppress structured logs
    enable_post_prompt_override: bool = False,  # Enable post-prompt override
    check_for_input_override: bool = False, # Enable input override
    config_file: Optional[str] = None       # Path to config file
)

Constructor Parameters​

ParameterTypeDefaultDescription
namestrrequiredAgent identifier
routestr"/"HTTP endpoint path
hoststr"0.0.0.0"Bind address
portint3000Bind port
basic_authTuple[str, str]NoneAuth credentials
use_pomboolTrueUse POM prompts
token_expiry_secsint3600Token TTL
auto_answerboolTrueAuto-answer calls
record_callboolFalseRecord calls
record_formatstr"mp4"Recording format
record_stereoboolTrueStereo recording
native_functionsList[str]NoneNative functions

Prompt Methods​

prompt_add_section​

def prompt_add_section(
    self,
    section: str,              # Section title
    body: str,                 # Section content
    bullets: List[str] = None  # Optional bullet points
) -> 'AgentBase'

Add a section to the agent's prompt.

prompt_add_text​

def prompt_add_text(
    self,
    text: str  # Text to add
) -> 'AgentBase'

Add raw text to the prompt.

get_prompt​

def get_prompt(self) -> Union[str, List[Dict]]

Get the complete prompt. Returns POM structure if use_pom=True, otherwise plain text.

Language and Voice Methods​

add_language​

def add_language(
    self,
    name: str,           # Language name (e.g., "English")
    code: str,           # Language code (e.g., "en-US")
    voice: str,          # Voice ID (e.g., "rime.spore")
    speech_fillers: Optional[List[str]] = None,  # Filler words
    function_fillers: Optional[List[str]] = None, # Processing phrases
    language_order: int = 0  # Priority order
) -> 'AgentBase'

Add a supported language with voice configuration.

set_voice​

def set_voice(
    self,
    voice: str  # Voice ID
) -> 'AgentBase'

Set the default voice for the agent.

Tool Definition Methods​

tool (decorator)​

@agent.tool(
    name: str = None,           # Function name (default: function name)
    description: str = "",      # Function description
    secure: bool = False,       # Require token authentication
    fillers: List[str] = None,  # Processing phrases
    wait_file: str = None       # Audio file URL for hold
)
def my_function(args...) -> SwaigFunctionResult:
    ...

Decorator to register a SWAIG function.

define_tool​

def define_tool(
    self,
    name: str,                          # Function name
    description: str,                   # Function description
    handler: Callable,                  # Function handler
    parameters: Dict[str, Any] = None,  # Parameter schema
    secure: bool = False,               # Require authentication
    fillers: List[str] = None,          # Processing phrases
    wait_file: str = None               # Hold audio URL
) -> 'AgentBase'

Programmatically define a SWAIG function.

Skill Methods​

add_skill​

def add_skill(
    self,
    skill_name: str,               # Skill identifier
    params: Dict[str, Any] = None  # Skill configuration
) -> 'AgentBase'

Add a skill to the agent.

list_available_skills​

def list_available_skills(self) -> List[str]

List all available skills.

AI Configuration Methods​

set_params​

def set_params(
    self,
    params: Dict[str, Any]  # AI parameters
) -> 'AgentBase'

Set AI model parameters (temperature, top_p, etc.).

add_hints​

def add_hints(
    self,
    hints: List[str]  # Speech recognition hints
) -> 'AgentBase'

Add speech recognition hints.

add_pronounce​

def add_pronounce(
    self,
    patterns: List[Dict[str, str]]  # Pronunciation rules
) -> 'AgentBase'

Add pronunciation rules.

State Methods​

set_global_data​

def set_global_data(
    self,
    data: Dict[str, Any]  # Data to store
) -> 'AgentBase'

Set initial global data for the agent session.

URL Methods​

get_full_url​

def get_full_url(
    self,
    include_auth: bool = False  # Include credentials in URL
) -> str

Get the full URL for the agent endpoint.

set_web_hook_url​

def set_web_hook_url(
    self,
    url: str  # Webhook URL
) -> 'AgentBase'

Override the default webhook URL.

set_post_prompt_url​

def set_post_prompt_url(
    self,
    url: str  # Post-prompt URL
) -> 'AgentBase'

Override the post-prompt summary URL.

Server Methods​

run​

def run(
    self,
    host: str = None,  # Override host
    port: int = None   # Override port
) -> None

Start the development server.

get_app​

def get_app(self) -> FastAPI

Get the FastAPI application instance.

Serverless Methods​

serverless_handler​

def serverless_handler(
    self,
    event: Dict[str, Any],  # Lambda event
    context: Any            # Lambda context
) -> Dict[str, Any]

Handle AWS Lambda invocations.

cloud_function_handler​

def cloud_function_handler(
    self,
    request  # Flask request
) -> Response

Handle Google Cloud Function invocations.

azure_function_handler​

def azure_function_handler(
    self,
    req  # Azure HttpRequest
) -> HttpResponse

Handle Azure Function invocations.

Callback Methods​

on_summary​

def on_summary(
    self,
    summary: Optional[Dict[str, Any]],  # Summary data
    raw_data: Optional[Dict[str, Any]] = None  # Raw POST data
) -> None

Override to handle post-prompt summaries.

set_dynamic_config_callback​

def set_dynamic_config_callback(
    self,
    callback: Callable  # Config callback
) -> 'AgentBase'

Set a callback for dynamic configuration.

SIP Routing Methods​

enable_sip_routing​

def enable_sip_routing(
    self,
    auto_map: bool = True,  # Auto-map usernames
    path: str = "/sip"      # Routing endpoint path
) -> 'AgentBase'

Enable SIP-based routing.

register_sip_username​

def register_sip_username(
    self,
    sip_username: str  # SIP username
) -> 'AgentBase'

Register a SIP username for routing.

Method Chaining​

All setter methods return self for method chaining:

from signalwire_agents import AgentBase
from signalwire_agents.core.function_result import SwaigFunctionResult

agent = (
    AgentBase(name="assistant", route="/assistant")
    .add_language("English", "en-US", "rime.spore")
    .add_hints(["SignalWire", "SWML", "SWAIG"])
    .set_params({"temperature": 0.7})
    .set_global_data({"user_tier": "standard"})
)

@agent.tool(description="Get help")
def get_help(topic: str) -> SwaigFunctionResult:
    return SwaigFunctionResult(f"Help for {topic}")

if __name__ == "__main__":
    agent.run()

Class Attributes​

AttributeTypeDescription
PROMPT_SECTIONSList[Dict]Declarative prompt sections
namestrAgent name
routestrHTTP route path
hoststrBind host
portintBind port
agent_idstrUnique agent identifier
pomPromptObjectPOM instance (if use_pom=True)
skill_managerSkillManagerSkill manager instance

See Also​

TopicReference
Creating prompts[Prompts Prompts & POM POM](/sdks/agents-sdk/building-agents/prompts-pom)
Voice configuration[Voice Voice & Language Language](/sdks/agents-sdk/building-agents/voice-language)
Function definitionsSWAIG Function API
Function resultsSwaigFunctionResult API
Multi-step workflowsContextBuilder API
Testing agentsswaig-test CLI

Common Usage Patterns​

Minimal Production Setup​

agent = AgentBase(
    name="support",
    route="/support",
    basic_auth=("user", "pass"),  # Always use auth in production
    record_call=True,             # Enable for compliance
    record_stereo=True            # Separate channels for analysis
)

High-Volume Configuration​

agent = AgentBase(
    name="ivr",
    route="/ivr",
    suppress_logs=True,           # Reduce logging overhead
    token_expiry_secs=1800        # Shorter token lifetime
)

Development Configuration​

agent = AgentBase(
    name="dev-agent",
    route="/",
    host="127.0.0.1",             # Localhost only
    port=3000
)
# Test with: swaig-test agent.py --dump-swml