***
title: Architecture
description: Understand the fundamental architecture, protocols, and patterns that power the SignalWire Agents SDK.
slug: /guides/architecture
max-toc-depth: 3
---------------------
For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt
[architecture]: /docs/server-sdks/guides/architecture
[swml]: /docs/server-sdks/guides/swml
[swaig]: /docs/server-sdks/guides/swaig
[lifecycle]: /docs/server-sdks/guides/lifecycle
[security]: /docs/server-sdks/guides/security
[swml-documents]: /docs/server-sdks/guides/swml
[ref-agentbase]: /docs/server-sdks/reference/python/agents/agent-base
[ref-datamap]: /docs/server-sdks/reference/python/agents/data-map
[ref-swmlservice]: /docs/server-sdks/reference/python/agents/swml-service
## What You'll Learn
This chapter covers the foundational concepts you need to build effective voice AI agents:
1. **Architecture** - How [AgentBase][ref-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
| Term | Definition |
| -------------------------- | -------------------------------------------------------------- |
| **AgentBase** | The base class all agents inherit from |
| **SWML** | SignalWire Markup Language - JSON format for call instructions |
| **SWAIG** | SignalWire AI Gateway - System for AI to call your functions |
| **Mixin** | A class providing specific functionality to AgentBase |
| **POM** | Prompt Object Model - Structured prompt building |
| **[DataMap][ref-datamap]** | Declarative REST API integration |
## Chapter Contents
| Section | Description |
| ---------------------------- | ------------------------------------- |
| [Architecture][architecture] | AgentBase class and mixin composition |
| [SWML][swml] | Understanding SWML document structure |
| [SWAIG][swaig] | How AI calls your functions |
| [Lifecycle][lifecycle] | Request/response flow |
| [Security][security] | Authentication and token security |
## Why These Concepts Matter
Understanding these core concepts helps you:
* **Debug effectively** - Know where to look when things go wrong
* **Build efficiently** - Use the right tool for each task
* **Scale confidently** - Understand how the system handles load
* **Extend properly** - Add custom functionality the right way
## The Mixin Composition Pattern
AgentBase doesn't inherit from a single monolithic class. Instead, it combines nine specialized mixins plus the SWMLService base class:
## Each Mixin's Role
### AuthMixin - Authentication & Security
Handles basic HTTP authentication for webhook endpoints.
| Language | Auth Configuration |
| ---------- | ---------------------------------------------------------------------- |
| Python | `AgentBase(name="my-agent")` -- credentials from env or auto-generated |
| TypeScript | `new AgentBase({ name: 'my-agent', basicAuth: ['user', 'pass'] })` |
**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.
```python
# Automatically registers these routes:
# GET / -> Returns SWML document
# POST / -> Returns SWML document
# POST /swaig -> Handles SWAIG function calls
# POST /post_prompt -> Receives call summaries
# 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][ref-swmlservice] - SWML Document Generation
The foundation for building SWML documents.
```python
# SWMLService provides:
# - Schema validation against SWML spec
# - Verb handler registry
# - 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).
| Language | Prompt Section |
| ---------- | ------------------------------------------------------------------------------ |
| Python | `agent.prompt_add_section("Role", "You are helpful.", bullets=[...])` |
| TypeScript | `agent.promptAddSection('Role', { body: 'You are helpful.', bullets: [...] })` |
**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.
| Language | Tool Definition |
| ---------- | ----------------------------------------------------------------------------------------------- |
| Python | `agent.define_tool(name="get_balance", description="...", parameters={...}, handler=fn)` |
| TypeScript | `agent.defineTool({ name: 'get_balance', description: '...', parameters: {...}, handler: fn })` |
**Key features:**
* Multiple registration methods (define\_tool, decorators, DataMap)
* Parameter validation
* Security token generation
### SkillMixin - Skill Plugin Management
Loads and manages reusable skill plugins.
| Language | Skill Loading |
| ---------- | ------------------------------------------- |
| Python | `agent.add_skill("datetime")` |
| TypeScript | `await agent.addSkill(new DateTimeSkill())` |
**Key features:**
* Auto-discovery of skill modules
* Dependency checking
* Configuration validation
### AIConfigMixin - AI Behavior Configuration
Configures the AI's voice, language, and behavior parameters.
| Language | Configuration |
| ---------- | ---------------------------------------------------------------------------- |
| Python | `agent.add_language("English", "en-US", "rime.spore")` |
| TypeScript | `agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rime.spore' })` |
**Key features:**
* Voice and language settings
* Speech recognition hints
* AI behavior parameters
### ServerlessMixin - Deployment Adapters
Provides handlers for serverless deployments.
```python
# AWS Lambda
handler = agent.serverless_handler
# Google Cloud Functions
def my_function(request):
return agent.cloud_function_handler(request)
# Azure Functions
def main(req):
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.
```python
# State is passed via global_data in SWML
# and preserved across function calls
```
**Key features:**
* Session tracking
* State persistence patterns
* Call context management
### MCPServerMixin - MCP Protocol Support
Exposes agent tools as an MCP (Model Context Protocol) server endpoint.
**Key features:**
* MCP JSON-RPC 2.0 protocol support
* Automatic tool exposure at `/mcp` endpoint
* Converts SWAIG functions to MCP tool format
## 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 functionality automatically:
```python
from signalwire import AgentBase, FunctionResult
class CustomerServiceAgent(AgentBase):
def __init__(self):
super().__init__(name="customer-service")
self.add_language("English", "en-US", "rime.spore")
self.set_params({"end_of_speech_timeout": 500})
self.prompt_add_section("Role", "You are a helpful agent.")
self.define_tool(
name="lookup_order",
description="Look up an order by ID",
parameters={"order_id": {"type": "string", "description": "Order ID"}},
handler=self.lookup_order
)
self.add_skill("datetime")
def lookup_order(self, args, raw_data):
order_id = args.get("order_id")
return FunctionResult(f"Order {order_id}: Shipped, arrives tomorrow")
if __name__ == "__main__":
agent = CustomerServiceAgent()
agent.run()
```
```typescript
import { AgentBase, FunctionResult } from 'signalwire-agents';
const agent = new AgentBase({ name: 'customer-service' });
agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rime.spore' });
agent.setParams({ end_of_speech_timeout: 500 });
agent.promptAddSection('Role', { body: 'You are a helpful agent.' });
agent.defineTool({
name: 'lookup_order',
description: 'Look up an order by ID',
parameters: { order_id: { type: 'string', description: 'Order ID' } },
handler: (args) => {
const result = new FunctionResult(`Order ${args.order_id}: Shipped, arrives tomorrow`);
return result;
},
});
agent.addSkill('datetime');
agent.run();
```
## Benefits of This Architecture
| Benefit | Description |
| -------------------------- | --------------------------------- |
| **Separation of Concerns** | Each mixin handles one domain |
| **Easy to Understand** | Look at one mixin for one feature |
| **Extensible** | Override specific mixin methods |
| **Testable** | Test mixins independently |
| **Type-Safe** | Full type hints throughout |
## Next Steps
Now that you understand how AgentBase is structured, let's look at the [SWML documents][swml-documents] it generates.