Deployment

Deploy your agents as local servers, production services, or serverless functions. This chapter covers all deployment options from development to production.

What You’ll Learn

This chapter covers deployment options:

1. Local Development - Running agents during development
2. Production - Deploying to production servers
3. Serverless - AWS Lambda, Google Cloud Functions, Azure Functions
4. Docker & Kubernetes - Container-based deployment
5. CGI Mode - Traditional web server deployment

Deployment Options Overview

Environment Detection

The SDK automatically detects your deployment environment:

Chapter Contents

Quick Start

1
from signalwire_agents import AgentBase
2
3
class MyAgent(AgentBase):
4
    def __init__(self):
5
        super().__init__(name="my-agent")
6
        self.add_language("English", "en-US", "rime.spore")
7
        self.prompt_add_section("Role", "You are a helpful assistant.")
8
9
if __name__ == "__main__":
10
    agent = MyAgent()
11
    agent.run()  # Automatically detects environment

The run() method automatically:

• Detects serverless environments (Lambda, Cloud Functions, Azure)
• Starts a development server on localhost for local development
• Handles CGI mode when deployed to traditional web servers

Starting the Development Server

The simplest way to run your agent locally:

1
from signalwire_agents import AgentBase
2
3
4
class MyAgent(AgentBase):
5
    def __init__(self):
6
        super().__init__(name="my-agent")
7
        self.add_language("English", "en-US", "rime.spore")
8
        self.prompt_add_section("Role", "You are a helpful assistant.")
9
10
11
if __name__ == "__main__":
12
    agent = MyAgent()
13
    agent.run()  # Starts on http://localhost:3000

Server Configuration

Custom Host and Port

1
agent.run(host="0.0.0.0", port=8080)

Using serve() Directly

For more control, use serve() instead of run():

1
# Development server
2
agent.serve(host="127.0.0.1", port=3000)
3
4
# Listen on all interfaces
5
agent.serve(host="0.0.0.0", port=3000)

Development Endpoints

Testing Your Agent

View SWML Output

$
# Get the SWML document
$
curl http://localhost:3000/
$
$
# Pretty print with jq
$
curl http://localhost:3000/ | jq .

Using swaig-test CLI

$
# List available functions
$
swaig-test my_agent.py --list-tools
$
$
# Test a specific function
$
swaig-test my_agent.py --exec get_weather --city "Seattle"
$
$
# Dump SWML output
$
swaig-test my_agent.py --dump-swml

Exposing Local Server

SignalWire needs to reach your agent via a public URL. Use ngrok or similar:

Connection Flow: SignalWire Cloud → ngrok tunnel → localhost:3000

Steps:

1. Start your agent: python my_agent.py
2. Start ngrok: ngrok http 3000
3. Use ngrok URL in SignalWire: https://abc123.ngrok.io

Using ngrok

$
# Start your agent
$
python my_agent.py
$
$
# In another terminal, start ngrok
$
ngrok http 3000

ngrok provides a public URL like https://abc123.ngrok.io that forwards to your local server.

Using localtunnel

$
# Install
$
npm install -g localtunnel
$
$
# Start tunnel
$
lt --port 3000

Environment Variables for Development

$
# Disable authentication for local testing
$
export SWML_BASIC_AUTH_USER=""
$
export SWML_BASIC_AUTH_PASSWORD=""
$
$
# Or set custom credentials
$
export SWML_BASIC_AUTH_USER="dev"
$
export SWML_BASIC_AUTH_PASSWORD="test123"
$
$
# Override proxy URL if behind ngrok
$
export SWML_PROXY_URL_BASE="https://abc123.ngrok.io"

Proxy URL Configuration

When behind ngrok or another proxy, the SDK needs to know the public URL:

1
import os
2
3
# Option 1: Environment variable
4
os.environ['SWML_PROXY_URL_BASE'] = 'https://abc123.ngrok.io'
5
6
# Option 2: Auto-detection from X-Forwarded headers
7
# The SDK automatically detects proxy from request headers

Development Workflow

1. Code

Write/modify your agent code.

2. Test Locally

• swaig-test my_agent.py --dump-swml
• swaig-test my_agent.py --exec function_name --param value

3. Run Server

python my_agent.py

4. Expose Publicly

ngrok http 3000

5. Test with SignalWire

Point phone number to ngrok URL and make test call.

Debug Mode

Enable debug logging:

1
import logging
2
logging.basicConfig(level=logging.DEBUG)
3
4
agent = MyAgent()
5
agent.run()

Or via environment variable:

$
export SIGNALWIRE_LOG_MODE=default
$
python my_agent.py

Hot Reloading

For automatic reloading during development, use uvicorn directly:

$
# Install uvicorn with reload support
$
pip install uvicorn[standard]
$
$
# Run with auto-reload
$
uvicorn my_agent:agent._app --reload --host 0.0.0.0 --port 3000

Or create a development script:

1
# dev.py
2
from my_agent import MyAgent
3
4
agent = MyAgent()
5
app = agent._app  # Expose the ASGI app for uvicorn

Then run:

$
uvicorn dev:app --reload --port 3000

Serving Static Files

Use AgentServer.serve_static_files() to serve static files alongside your agents. This is useful for web dashboards, documentation, or any static content:

1
from signalwire_agents import AgentServer
2
from pathlib import Path
3
4
# Create your agents
5
from my_agents import SupportAgent, SalesAgent
6
7
HOST = "0.0.0.0"
8
PORT = 3000
9
10
server = AgentServer(host=HOST, port=PORT)
11
server.register(SupportAgent(), "/support")
12
server.register(SalesAgent(), "/sales")
13
14
# Serve static files from web directory
15
web_dir = Path(__file__).parent / "web"
16
if web_dir.exists():
17
    server.serve_static_files(str(web_dir))
18
19
server.run()

Directory Structure:

Key Points:

• Use server.serve_static_files(directory) to serve static files
• Agent routes always take priority over static files
• Requests to / serve index.html from the static directory
• Both /support and /support/ work correctly with agents

Route Priority:

Common Development Issues