Architecture

What You’ll Learn

This chapter covers the foundational concepts you need to build effective voice AI agents:

1. Architecture - How AgentBase and its mixins work together
2. SWML - The markup language that controls call flows
3. SWAIG - The gateway that lets AI call your functions
4. Lifecycle - How requests flow through the system
5. Security - Authentication and token-based function security

Prerequisites

Before diving into these concepts, you should have:

• Completed the Getting Started chapter
• A working agent running locally
• Basic understanding of HTTP request/response patterns

The Big Picture

Key Terminology

The Mixin Composition Pattern

AgentBase doesn’t inherit from a single monolithic class. Instead, it combines eight specialized mixins:

Each Mixin’s Role

AuthMixin - Authentication & Security

Handles basic HTTP authentication for webhook endpoints.

1
from signalwire_agents import AgentBase
2
3
class MyAgent(AgentBase):
4
    def __init__(self):
5
        super().__init__(name="my-agent")
6
        # Auth credentials auto-generated or from environment:
7
        # SWML_BASIC_AUTH_USER, SWML_BASIC_AUTH_PASSWORD

Key methods:

• Validates incoming requests against stored credentials
• Generates credentials if not provided via environment
• Protects SWAIG function endpoints

WebMixin - HTTP Server & Routing

Manages the FastAPI application and HTTP endpoints.

1
# Automatically registers these routes:
2
# GET  /          → Returns SWML document
3
# POST /          → Returns SWML document
4
# POST /swaig     → Handles SWAIG function calls
5
# POST /post_prompt → Receives call summaries
6
# GET  /debug     → Debug information (dev only)

Key features:

• Runs uvicorn server via agent.run()
• Handles proxy detection (ngrok, load balancers)
• Manages request/response lifecycle

SWMLService - SWML Document Generation

The foundation for building SWML documents.

1
# SWMLService provides:
2
# - Schema validation against SWML spec
3
# - Verb handler registry
4
# - Document rendering pipeline

Key responsibilities:

• Validates SWML structure against JSON schema
• Registers verb handlers (answer, ai, connect, etc.)
• Renders final SWML JSON

PromptMixin - Prompt Management

Manages AI system prompts using POM (Prompt Object Model).

1
agent.prompt_add_section(
2
    "Role",
3
    "You are a helpful customer service agent."
4
)
5
6
agent.prompt_add_section(
7
    "Guidelines",
8
    body="Follow these rules:",
9
    bullets=[
10
        "Be concise",
11
        "Be professional",
12
        "Escalate when needed"
13
    ]
14
)

Key features:

• Structured prompt building with sections
• Support for bullets, subsections
• Post-prompt for call summaries

ToolMixin - SWAIG Function Management

Handles registration and execution of SWAIG functions.

1
agent.define_tool(
2
    name="get_balance",
3
    description="Get account balance",
4
    parameters={
5
        "account_id": {
6
            "type": "string",
7
            "description": "The account ID"
8
        }
9
    },
10
    handler=self.get_balance
11
)

Key features:

• Multiple registration methods (define_tool, decorators, DataMap)
• Parameter validation
• Security token generation

SkillMixin - Skill Plugin Management

Loads and manages reusable skill plugins.

1
# Load built-in skill
2
agent.add_skill("datetime")
3
4
# Load skill with configuration
5
agent.add_skill("web_search",
6
    google_api_key="...",
7
    google_cx_id="..."
8
)

Key features:

• Auto-discovery of skill modules
• Dependency checking
• Configuration validation

AIConfigMixin - AI Behavior Configuration

Configures the AI’s voice, language, and behavior parameters.

1
agent.add_language("English", "en-US", "rime.spore")
2
3
agent.set_params({
4
    "end_of_speech_timeout": 500,
5
    "attention_timeout": 15000
6
})
7
8
agent.add_hints(["SignalWire", "SWML", "AI agent"])

Key features:

• Voice and language settings
• Speech recognition hints
• AI behavior parameters

ServerlessMixin - Deployment Adapters

Provides handlers for serverless deployments.

1
# AWS Lambda
2
handler = agent.serverless_handler
3
4
# Google Cloud Functions
5
def my_function(request):
6
    return agent.cloud_function_handler(request)
7
8
# Azure Functions
9
def main(req):
10
    return agent.azure_function_handler(req)

Key features:

• Environment auto-detection
• Request/response adaptation
• URL generation for each platform

StateMixin - State Management

Manages session and call state.

1
# State is passed via global_data in SWML
2
# and preserved across function calls

Key features:

• Session tracking
• State persistence patterns
• Call context management

Key Internal Components

Beyond the mixins, AgentBase uses several internal managers:

ToolRegistry

• Stores SWAIG functions
• Handles function lookup
• Generates webhook URLs

PromptManager

• Manages prompt sections
• Builds POM structure
• Handles post-prompts

SessionManager

• Token generation
• Token validation
• Security enforcement

SkillManager

• Skill discovery
• Skill loading
• Configuration validation

SchemaUtils

• SWML schema loading
• Document validation
• Schema-driven help

VerbHandlerRegistry

• Verb registration
• Handler dispatch
• Custom verb support

Creating Your Own Agent

When you create an agent, you get all mixin functionality automatically:

1
from signalwire_agents import AgentBase, SwaigFunctionResult
2
3
4
class CustomerServiceAgent(AgentBase):
5
    def __init__(self):
6
        super().__init__(name="customer-service")
7
8
        # AIConfigMixin methods
9
        self.add_language("English", "en-US", "rime.spore")
10
        self.set_params({"end_of_speech_timeout": 500})
11
12
        # PromptMixin methods
13
        self.prompt_add_section("Role", "You are a helpful agent.")
14
15
        # ToolMixin methods
16
        self.define_tool(
17
            name="lookup_order",
18
            description="Look up an order by ID",
19
            parameters={
20
                "order_id": {"type": "string", "description": "Order ID"}
21
            },
22
            handler=self.lookup_order
23
        )
24
25
        # SkillMixin methods
26
        self.add_skill("datetime")
27
28
    def lookup_order(self, args, raw_data):
29
        order_id = args.get("order_id")
30
        # Your business logic here
31
        return SwaigFunctionResult(f"Order {order_id}: Shipped, arrives tomorrow")
32
33
34
if __name__ == "__main__":
35
    agent = CustomerServiceAgent()
36
    agent.run()  # WebMixin method

Benefits of This Architecture

Next Steps

Now that you understand how AgentBase is structured, let’s look at the SWML documents it generates.