data_map.output

Similar to a return statement in conventional programming languages, the data_map.output object immediately terminates function execution and returns control to the caller. When encountered, it returns two values:

1. A response object: Contains static text that will be incorporated into the AI agent's context
2. An action object: Defines one or more executable actions that are triggered when the SWAIG function successfully completes

Just as a return statement prevents any subsequent code from executing in a traditional function, once data_map.output is processed, no further instructions within the SWAIG function will be executed.

Name	Type	Default	Description
outputRequired	object	-	An object that accepts the output Parameters.

output Parameters

When a SWAIG function is executed, the functions expects the user to respond with a JSON object that contains a response key and an optional action key. This request response is used to provide the LLM with a new prompt response via the response key and to execute SWML-compatible objects that will perform new dialplan actions via the action key.

Name	Type	Default	Description
responseRequired	string	-	Static text that will be added to the AI agent's context.
actionOptional	object[]	-	A list of SWML-compatible objects that are executed upon the execution of a SWAIG function.

---

List of valid actions

Name	Type	Default	Description
SWML	object	-	A SWML object to be executed.
say	string	-	A message to be spoken by the AI agent.
stop	boolean	-	Whether to stop the conversation.
toggle_functions	object[]	-	Whether to toggle the functions on or off.
toggle_functions.active	boolean	true	Whether to activate or deactivate the functions.
toggle_functions.function	object[]	-	A list of functions to toggle.
set_global_data	object	-	A JSON object containing any global data, as a key-value map. This action sets the data in the global_data to be globally referenced.
set_meta_data	object	-	A JSON object containing any metadata, as a key-value map. This action sets the data in the meta_data to be referenced locally in the function.
unset_global_data	string | object	-	The key of the global data to unset from the global_data. You can also reset the global_data by passing in a new object.
unset_meta_data	string | object	-	The key of the metadata to unset from the meta_data. You can also reset the meta_data by passing in a new object.
playback_bg	object	-	A JSON object containing the audio file to play.
playback_bg.file	string	-	URL or filepath of the audio file to play. Authentication can also be set in the url in the format of username:password@url.
playback_bg.wait	boolean	false	Whether to wait for the audio file to finish playing before continuing.
stop_playback_bg	boolean	-	Whether to stop the background audio file.
user_input	string	-	Used to inject text into the users queue as if they input the data themselves.
context_switch	object	-	A JSON object containing the context to switch to.
context_switch.system_prompt	string	-	The instructions to send to the agent.
context_switch.consolidate	boolean	false	Whether to consolidate the context.
context_switch.user_prompt	string	-	A string serving as simulated user input for the AI Agent. During a context_switch in the AI's prompt, the user_prompt offers the AI pre-established context or guidance.

Example

YAML

sections:
  main:
    - ai:
        prompt:
          text: You are a helpful SignalWire assistant.
        SWAIG:
          functions:
            - function: test_function
              description: This is a test function.
              parameters:
                type: object
                properties:
                  name:
                    type: string
                    description: The name of the person.
                required:
                  - name
              data_map:
                output:
                  response: We are testing the function.
                  action:
                    - SWML:
                        sections:
                          main:
                            - play:
                                url: 'say:We are testing the function.'

JSON

{
  "sections": {
    "main": [
      {
        "ai": {
          "prompt": {
            "text": "You are a helpful SignalWire assistant."
          },
          "SWAIG": {
            "functions": [
              {
                "function": "test_function",
                "description": "This is a test function.",
                "parameters": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "The name of the person."
                    }
                  },
                  "required": [
                    "name"
                  ]
                },
                "data_map": {
                  "output": {
                    "response": "We are testing the function.",
                    "action": [
                      {
                        "SWML": {
                          "sections": {
                            "main": [
                              {
                                "play": {
                                  "url": "say:We are testing the function."
                                }
                              }
                            ]
                          }
                        }
                      }
                    ]
                  }
                }
              }
            ]
          }
        }
      }
    ]
  }
}