> 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 ## Docs - [Enable functions dynamically](https://signalwire.com/docs/swml/guides/toggle-functions.md): Learn how to use `toggle_functions` to toggle functions on and off. - [Execute SWML from a function](https://signalwire.com/docs/swml/guides/executing-swml.md): Learn how to execute SWML from a SWAIG function. - [Handle SWAIG function calls inline](https://signalwire.com/docs/swml/guides/data-map.md): Learn how to use `data_map` in SWML SWAIG functions to process, transform, and utilize incoming data effectively. - [Store data outside LLM context](https://signalwire.com/docs/swml/guides/set-meta-data.md): Learn how to use the `set_meta_data` action to store function metadata without exposing it to the LLM. - [Switch AI context mid-call](https://signalwire.com/docs/swml/guides/context-switch.md): Learn how to use `context_switch` to shift the focus of the conversation. > **Note:** This page contains both a page directory (above) and the landing page content (below). The page directory is generated for agent use and does not appear on the landing page. > 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 > The SignalWire AI Gateway connects your AI Agents to functionality on your backend. SWAIG is a JSON protocol over HTTP. It is how an AI Agent calls code you host: SignalWire POSTs a JSON object to your endpoint, and your endpoint returns a JSON object. This is the same idea as tool calling with any LLM API — see the [tool calling guide](/docs/platform/ai/tool-calling) for the architecture and the complete field-by-field protocol. Each request body contains the function name (for example `"search_movie"`), the arguments the agent extracted in `argument.parsed`, the argument schema you declared in `argument_desc`, and the call's session, caller, and project identifiers. Each reply contains `response`, the text added to the agent's context, and optionally `action`, SWML-compatible objects that change what the call does next. ## Remote functions ### Accept a POST request When a SWAIG function is invoked by the AI Agent, your server receives a JSON payload containing: * The `function` name to be executed. * The structured arguments in `argument.parsed`. * Contextual metadata (caller ID, project ID, session ID, etc.). From this request, extract the function name and `argument.parsed`. #### Example SWAIG function The following sample SWML creates the SWAIG function `search_movie`: ```json { "description": "Search for movies by title", "function": "search_movie", "parameters": { "properties": { "include_adult": { "description": "Whether to include adult content", "type": "boolean" }, "language": { "description": "Language of the results", "type": "string" }, "page": { "description": "Page number for pagination", "type": "integer" }, "primary_release_year": { "description": "Filter results by primary release year", "type": "integer" }, "query": { "description": "The movie title to search for", "type": "string" }, "region": { "description": "Specify a region to prioritize search results", "type": "string" }, "year": { "description": "Filter results by release year", "type": "integer" } }, "required": [], "type": "object" }, "web_hook_url": "https://username:password@moviebot.example.com/swaig" } ``` #### Example request sent to server When your SWAIG function executes, SignalWire sends a request like the following to your server. ```json { "function": "search_movie", "argument": { "parsed": [ { "query": "Pretty Woman" } ], "raw": "{\"query\":\"Pretty Woman\"}" }, "argument_desc": { "properties": { "query": { "type": "string", "description": "The movie title to search for" }, "year": { "type": "integer" } }, "type": "object" }, "ai_session_id": "c960da54-3f09-4de6-8c84-49c1fcca704c", "caller_id_num": "+19184249378", "project_id": "625ceaeb-b27c-46b9-9b69-9d62286588ec" } ``` ### Execute business logic On your server, perform the actions needed to generate the desired response using the extracted function name and arguments. In this case, our application retrieves information about a selected movie from an external API. ### Return a `response` message The response can directly shape the AI Agent’s next moves using natural language and SWML instructions. In reply, your server should return a JSON object with the following: * **`response`** (string): A message in Markdown format used by the LLM in its reply. * **`action`** (array): Optional list of SWML-compatible objects that can execute commands, play media, set metadata, or return inline SWML. For example: #### Response to SWAIG request Note that this response includes both **response** and **action** sections. This means that our server has both updated the LLM's context with the requested information from an external API, ***and*** handed off new call flow instructions in the form of valid SWML. ```json { "response": "**Pretty Woman** is a 1990 romantic comedy starring *Julia Roberts* as Vivian Ward, a spirited Hollywood escort, and *Richard Gere* as Edward Lewis, a wealthy businessman. Directed by Garry Marshall, the film tells the story of their unexpected romance that begins as a business deal and blossoms into a modern fairytale. \nSet against the glitz of Los Angeles, the movie features iconic moments—like the Rodeo Drive shopping spree and a memorable opera night. It explores themes of class, love, transformation, and empowerment. Julia Roberts' performance won her a Golden Globe and an Oscar nomination. It's now considered one of the most iconic romantic comedies ever made.", "action": [ { "set_meta_data": { "title": "Pretty Woman", "release_year": 1990, "genre": ["Romance", "Comedy"], "lead_actors": ["Julia Roberts", "Richard Gere"] } }, { "SWML": { "version": "1.0.0", "sections": { "main": [ { "play": { "url": "https://cdn.signalwire.com/swml/pretty-woman-theme.mp3" } } ] } } } ] } ```