signalwire.agent_server¶
signalwire.agent_server
¶
Copyright (c) 2025 SignalWire
This file is part of the SignalWire SDK.
Licensed under the MIT License. See LICENSE file in the project root for full license information.
AgentServer - Class for hosting multiple SignalWire AI Agents in a single server
AgentServer
¶
Server for hosting multiple SignalWire AI Agents under a single FastAPI application.
This allows you to run multiple agents on different routes of the same server, which is useful for deployment and resource management.
Example
server = AgentServer() server.register(SupportAgent(), "/support") server.register(SalesAgent(), "/sales") server.run()
host = host
instance-attribute
¶
port = port
instance-attribute
¶
log_level = log_level.lower()
instance-attribute
¶
logger = get_logger('AgentServer')
instance-attribute
¶
app = FastAPI(title='SignalWire AI Agents', description='Hosted SignalWire AI Agents', version='3.0.2', redirect_slashes=False, docs_url=None, redoc_url=None, openapi_url=None)
instance-attribute
¶
agents = {}
instance-attribute
¶
__init__(host='0.0.0.0', port=3000, log_level='info')
¶
Initialize a new agent server
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
host
|
str
|
Host to bind the server to |
'0.0.0.0'
|
port
|
int
|
Port to bind the server to |
3000
|
log_level
|
str
|
Logging level (debug, info, warning, error, critical) |
'info'
|
register(agent, route=None)
¶
Register an agent with the server
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agent
|
AgentBase
|
The agent to register |
required |
route
|
str | None
|
Optional route to override the agent's default route |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If the route is already in use |
setup_sip_routing(route='/sip', auto_map=True)
¶
Set up central SIP-based routing for the server
This configures all agents to handle SIP requests at the specified path, using a coordinated routing system where each agent checks if it can handle SIP requests for specific usernames.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
route
|
str
|
The path for SIP routing (default: "/sip") |
'/sip'
|
auto_map
|
bool
|
Whether to automatically map SIP usernames to agent routes |
True
|
register_sip_username(username, route)
¶
Register a mapping from SIP username to agent route
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
username
|
str
|
The SIP username |
required |
route
|
str
|
The route to the agent |
required |
unregister(route)
¶
Unregister an agent from the server
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
route
|
str
|
The route of the agent to unregister |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if the agent was unregistered, False if not found |
get_agents()
¶
Get all registered agents
Returns:
| Type | Description |
|---|---|
list[tuple[str, AgentBase]]
|
List of (route, agent) tuples |
get_agent(route)
¶
Get an agent by route
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
route
|
str
|
The route of the agent |
required |
Returns:
| Type | Description |
|---|---|
AgentBase | None
|
The agent or None if not found |
run(event=None, context=None, host=None, port=None)
¶
Universal run method that automatically detects environment and handles accordingly
Detects execution mode and routes appropriately: - Server mode: Starts uvicorn server with FastAPI - CGI mode: Uses same routing logic but outputs CGI headers - Lambda mode: Uses same routing logic but returns Lambda response
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event
|
Serverless event object (Lambda, Cloud Functions) |
None
|
|
context
|
Serverless context object (Lambda, Cloud Functions) |
None
|
|
host
|
str | None
|
Optional host to override the default (server mode only) |
None
|
port
|
int | None
|
Optional port to override the default (server mode only) |
None
|
Returns:
| Type | Description |
|---|---|
Any
|
Response for serverless modes, None for server mode |
register_global_routing_callback(callback_fn, path)
¶
Register a routing callback across all agents
This allows you to add unified routing logic to all agents at the same path.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
callback_fn
|
Callable[[Request, dict[str, Any]], str | None]
|
The callback function to register |
required |
path
|
str
|
The path to register the callback at |
required |
serve_static_files(directory, route='/')
¶
Serve static files from a directory.
This method properly integrates static file serving with agent routes, ensuring that agent routes take priority over static files.
Unlike using StaticFiles.mount("/", ...) directly on self.app, this method uses explicit route handlers that work correctly with agent routes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
directory
|
str
|
Path to the directory containing static files |
required |
route
|
str
|
URL path prefix for static files (default: "/" for root) |
'/'
|