Configuration

Configuration files

View as Markdown

Config files

Config files enable granular, isolated control of development, staging, and production environments, and allow substitution of sensitive values using environment variables.

Usage

Auto-load

The simplest way to start is to place a config.json file next to your agent in the project directory. It will be loaded automatically.

config.json
dev-agent.py
venv

Declare path

If you want to specify the path to your config file, pass it in using the config_file parameter.

agent.py
1from signalwire_agents import AgentBase
2
3# Create an agent
4agent = AgentBase(name="Sigmond", config_file="./path/to/config.json")
5
6# Start the agent
7agent.serve()

Structure

Configuration files support both JSON and YAML formats with environment variable substitution. Here’s a complete example showing the main configuration sections:

1{
2  "service": {
3    "name": "my-service",
4    "host": "${HOST|0.0.0.0}",
5    "port": "${PORT|3000}"
6  },
7  "security": {
8    "ssl_enabled": "${SSL_ENABLED|false}",
9    "ssl_cert_path": "${SSL_CERT|/etc/ssl/cert.pem}",
10    "ssl_key_path": "${SSL_KEY|/etc/ssl/key.pem}",
11    "auth": {
12      "basic": {
13        "enabled": true,
14        "user": "${AUTH_USER|signalwire}",
15        "password": "${AUTH_PASSWORD}"
16      },
17      "bearer": {
18        "enabled": "${BEARER_ENABLED|false}",
19        "token": "${BEARER_TOKEN}"
20      }
21    },
22    "allowed_hosts": ["${PRIMARY_HOST}", "${SECONDARY_HOST|localhost}"],
23    "cors_origins": "${CORS_ORIGINS|*}",
24    "rate_limit": "${RATE_LIMIT|60}"
25  }
26}

Service options

OptionTypeDefaultDescription
service.namestring-Service name for identification. This is the name set when instantiating your agent.
service.hoststring"0.0.0.0"Host/IP address to bind to
service.portnumber3000Port number to listen on
service.routestring"/"Base route path for the service

Security options

All services share the same security configuration options:

OptionTypeDefaultDescription
ssl_enabledbooleanfalseEnable HTTPS/SSL encryption
ssl_cert_pathstring-Path to SSL certificate file
ssl_key_pathstring-Path to SSL private key file
domainstring-Domain name for SSL configuration
allowed_hostsarray["*"]List of allowed host headers
cors_originsarray["*"]List of allowed CORS origins
max_request_sizenumber10485760Maximum request size in bytes (10MB)
rate_limitnumber60Requests per minute
request_timeoutnumber30Request timeout in seconds
use_hstsbooleantrueEnable HTTP Strict Transport Security
hsts_max_agenumber31536000HSTS max age in seconds (1 year)

Here’s a comprehensive example:

1{
2  "security": {
3    "ssl_enabled": true,
4    "ssl_cert_path": "/etc/ssl/cert.pem",
5    "ssl_key_path": "/etc/ssl/key.pem",
6    "domain": "api.example.com",
7
8    "allowed_hosts": ["api.example.com", "app.example.com"],
9    "cors_origins": ["https://app.example.com"],
10
11    "max_request_size": 5242880,
12    "rate_limit": 30,
13    "request_timeout": 60,
14
15    "use_hsts": true,
16    "hsts_max_age": 31536000
17  }
18}

Agent options

OptionTypeDefaultDescription
agent.auto_answerbooleantrueAutomatically answer incoming calls
agent.record_callbooleanfalseEnable call recording
agent.record_formatstring"mp4"Recording format (mp3, mp4, wav)
agent.record_stereobooleantrueRecord in stereo (separate channels for each party)
agent.token_expiry_secsnumber3600Token expiration time in seconds
agent.use_pombooleantrueUse Prompt Object Model for prompt construction
1{
2  "agent": {
3    "auto_answer": true,
4    "record_call": true,
5    "record_format": "mp3",
6    "record_stereo": true,
7    "token_expiry_secs": 7200,
8    "use_pom": true
9  }
10}

Skills options

Skills can be activated and configured via the config file:

OptionTypeDescription
skills[].namestringSkill identifier (e.g., datetime, math, native_vector_search)
skills[].paramsobjectSkill-specific configuration parameters
1{
2  "skills": [
3    { "name": "datetime" },
4    { "name": "math" },
5    {
6      "name": "native_vector_search",
7      "params": {
8        "index_path": "./knowledge.swsearch",
9        "tool_name": "search_docs",
10        "tool_description": "Search the knowledge base"
11      }
12    }
13  ]
14}

Logging options

OptionTypeDefaultDescription
logging.levelstring"info"Log level (debug, info, warning, error)
logging.formatstring"structured"Output format (structured, plain)
logging.modestring"default"Logging mode (default, off)
1{
2  "logging": {
3    "level": "info",
4    "format": "structured",
5    "mode": "default"
6  }
7}

Prioritization

Services in the Agents SDK look for configuration files in the below locations, in this order:

  1. Service-specific: {service_name}_config.json (e.g., search_config.json)
  2. Generic: config.json
  3. Hidden: .swml/config.json
  4. User home: ~/.swml/config.json
  5. System: /etc/swml/config.json

Configuration values are applied in this order (highest to lowest):

  1. Constructor parameters - Explicitly passed to service
  2. Config file values - From JSON configuration
  3. Environment variables - Direct env vars
  4. Defaults - Hard-coded defaults

The SDK validates config files on load, checking for required fields, correct types, and valid file paths (e.g., SSL certificates).

Environment variables

Substitution

The configuration system supports ${VAR|default} syntax:

  • ${VAR} - Use environment variable VAR (error if not set)
  • ${VAR|default} - Use VAR or “default” if not set
  • ${VAR|} - Use VAR or empty string if not set

For example:

config.json
1{
2  "database": {
3    "host": "${DB_HOST|localhost}",
4    "port": "${DB_PORT|5432}",
5    "password": "${DB_PASSWORD}"
6  }
7}
Set environment variables

Environment variables can be set in several ways depending on your deployment method. For example:

Create a .env file in your project root (add to .gitignore):

.env
$DB_PASSWORD=mysecretpassword
$SSL_ENABLED=true
$AUTH_USER=myuser

Optionally, use python-dotenv to load the .env variables:

$pip install python-dotenv
1from dotenv import load_dotenv
2load_dotenv()  # This loads the .env file

For serverless deployment, refer to each provider’s docs on managing environment variables:

AWS Lambda

Configure environment variables for Lambda functions

Google Cloud Functions

Set environment variables in Cloud Functions

Azure Functions

Manage app settings and environment variables

Examples

Development

This simple config sets up basic auth without SSL on port 3000.

1{
2  "service": {
3    "host": "localhost",
4    "port": 3000
5  },
6  "security": {
7    "ssl_enabled": false,
8    "auth": {
9      "basic": {
10        "user": "dev",
11        "password": "devpass123"
12      }
13    }
14  }
15}

Production

This config secures your service with SSL encryption, domain-based host restrictions, and environment variable substitution for sensitive credentials.

1{
2  "service": {
3    "host": "${HOST|0.0.0.0}",
4    "port": "${PORT|443}"
5  },
6  "security": {
7    "ssl_enabled": true,
8    "ssl_cert_path": "${SSL_CERT_PATH}",
9    "ssl_key_path": "${SSL_KEY_PATH}",
10    "domain": "${DOMAIN}",
11    "auth": {
12      "basic": {
13        "user": "${AUTH_USER}",
14        "password": "${AUTH_PASSWORD}"
15      }
16    },
17    "allowed_hosts": ["${DOMAIN}"],
18    "use_hsts": true
19  }
20}

Best practices

  1. Use environment substitution for sensitive values
  2. Validate configurations before deploying to production
  3. Document custom configurations for your team
  4. Test configurations in staging environments first
  5. Version control non-sensitive configuration templates
  6. Monitor configuration loading in application logs

For detailed security configuration options, see the Security guide.