> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# SWAIG

> Functions and MCP servers the ai_sidecar observer can call while watching a call.

[ai_sidecar]: /docs/swml/reference/calling/ai-sidecar

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`** `string` — required

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`** `string` — required

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`** `boolean` — default: 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.

---

> **Warning**
>
> 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](/docs/swml/reference/calling/ai-sidecar#built-in-sidecar_skip-tool).

## **Examples**

#### YAML

```yaml
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}"
```

#### JSON

```json
{
  "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}"
                }
              }
            ]
          }
        }
      }
    ]
  }
}
```

> Functions and MCP servers the ai_sidecar observer can call while watching a call.