Configuration

The SignalWire Agents SDK uses a layered configuration system. Settings can come from constructor parameters, environment variables, JSON config files, or sensible defaults. The layers are resolved in priority order:

1. Constructor parameters — highest priority
2. Config file values — loaded from JSON, override environment variables
3. Environment variables — override defaults
4. Defaults — built-in fallback values

1
from signalwire import AgentBase
2
3
# Constructor parameters take precedence over everything else
4
agent = AgentBase(
5
    name="my-agent",
6
    port=9000,                        # Overrides PORT env var and config file
7
    config_file="my_config.json",     # Explicit config file path
8
)

Config File Discovery

When no explicit config_file is provided, the SDK searches for JSON config files in this order:

1. config.json
2. agent_config.json
3. swml_config.json
4. .swml/config.json
5. ~/.swml/config.json
6. /etc/swml/config.json

See ConfigLoader for the full file discovery logic and environment variable substitution syntax.

Key Configuration Areas

Quick Example

1
{
2
  "service": {
3
    "name": "support-agent",
4
    "host": "0.0.0.0",
5
    "port": 8080,
6
    "route": "/support"
7
  },
8
  "security": {
9
    "auth": {
10
      "basic": {
11
        "user": "${AUTH_USER|support_agent}",
12
        "password": "${AUTH_PASSWORD}"
13
      }
14
    },
15
    "ssl_enabled": true,
16
    "domain": "support.example.com",
17
    "ssl_cert_path": "/etc/ssl/certs/support.crt",
18
    "ssl_key_path": "/etc/ssl/private/support.key"
19
  },
20
  "agent": {
21
    "auto_answer": true,
22
    "record_call": false
23
  },
24
  "skills": [
25
    { "name": "datetime" },
26
    {
27
      "name": "native_vector_search",
28
      "params": {
29
        "index_file": "./support_docs.swsearch",
30
        "tool_name": "search_support"
31
      }
32
    }
33
  ]
34
}