SWAIG | SignalWire

SWAIG (SignalWire AI Gateway) is SignalWire’s function-calling system for AI. It lets the sidecar’s model call functions that you define and run on your own server, so it can do more than just talk.

While the sidecar watches the call, the model can call a function whenever it needs to look something up or take an action — look up an account, flag a sales signal, update the agent’s screen, and so on. When it does, the sidecar sends a request to that function’s webhook (web_hook_url), your server runs the function and returns a result, and the model uses that result in its next response.

You define these functions under functions. You can also connect external MCP (Model Context Protocol) servers under mcp_servers, and their tools become available to the model the same way.

Properties

ai_sidecar.SWAIG

object

An object that defines the functions and MCP servers available to the sidecar.

SWAIG.defaults

object

Default settings applied to every function that does not override them.

defaults.web_hook_url

string

Default webhook URL for functions without their own web_hook_url. Authentication can also be set in the url in the format of username:password@url. Credentials embedded in the URL take precedence over web_hook_auth_user and web_hook_auth_password.

defaults.web_hook_auth_user

string

Default username for basic auth on the function webhook, for functions that don’t set their own web_hook_auth_user.

defaults.web_hook_auth_password

string

Default password for basic auth on the function webhook, for functions that don’t set their own web_hook_auth_password.

SWAIG.functions

object[]

An array of functions the model can call during the conversation.

functions[].function

stringRequired

The name of the function. This is the only required field — the model calls the function by this name.

functions[].description

string

A description of what the function does, sent to the model so it knows when to call it.

functions[].purpose

string

A fallback for description, used only when description is not set.

functions[].parameters

object

The JSON-Schema object describing the function’s arguments: type: object with a properties map and an optional required array. Each property allows only type, description, enum, and default — additional validation keywords such as pattern, minimum, and maximum are not accepted; express those constraints in the property description and validate them server-side. When omitted, the function takes no arguments.

functions[].web_hook_url

string

Webhook URL for this function. Falls back to defaults.web_hook_url. Authentication can also be set in the url in the format of username:password@url. Credentials embedded in the URL take precedence over web_hook_auth_user and web_hook_auth_password.

functions[].web_hook_auth_user

string

Username for basic auth on this function’s webhook. Falls back to defaults.web_hook_auth_user.

functions[].web_hook_auth_password

string

Password for basic auth on this function’s webhook. Falls back to defaults.web_hook_auth_password.

SWAIG.mcp_servers

object[]

An array of MCP (Model Context Protocol) servers whose tools and resources are made available to the AI. Each server’s tools are discovered at startup and registered as callable functions, so they can be invoked like any other SWAIG function.

mcp_servers[].url

stringRequired

The MCP server URL.

mcp_servers[].headers

object

HTTP headers sent to the MCP server. Authorization tokens go here — there is no separate auth field. Header values support variable expansion (e.g. Bearer ${global_data.token}).

mcp_servers[].resources

booleanDefaults to false

Whether to fetch the server’s resources into global_data, when the server advertises resource support.

mcp_servers[].resource_vars

object

Template variables passed to the MCP server when fetching resources. Used only when resources is enabled.

The function name sidecar_skip is reserved. It is auto-registered as a built-in tool — do not declare a function with that name. See Built-in sidecar_skip tool.

Examples

version: 1.0.0
sections:
  main:
    - ai_sidecar:
        prompt: "Coach the agent."
        lang: "en-US"
        SWAIG:
          defaults:
            web_hook_url: "https://your-app.example.com/sidecar/swaig"
          functions:
            - function: lookup_competitor
              description: "Look up a competitor by name."
              parameters:
                type: object
                properties:
                  competitor:
                    type: string
                    description: "Competitor name."
                required:
                  - competitor
          mcp_servers:
            - url: "https://crm.example.com/mcp"
              headers:
                Authorization: "Bearer ${global_data.crm_token}"
              resources: true
              resource_vars:
                customer_id: "${global_data.customer_id}"