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.

data_map.output

objectrequired

An object that accepts the output Parameters.

output Parameters

output.response

stringrequired

Static text that will be added to the AI agent's context.

output.action

object[]

A list of SWML-compatible objects that are executed upon the execution of a SWAIG function.

See list of valid actions for additional details.

List of valid actions

action[].SWML

object

A SWML object to be executed.

action[].say

string

A message to be spoken by the AI agent.

action[].stop

boolean

Whether to stop the conversation.

action[].change_context

string

The name of the context to switch to. The context must be defined in the AI's prompt.contexts configuration. This action triggers an immediate context switch during the execution of a SWAIG function.

Visit the contexts documentation for details on defining contexts.

action[].change_step

string

The name of the step to switch to. The step must be defined in prompt.contexts.{context_name}.steps for the current context. This action triggers an immediate step transition during the execution of a SWAIG function.

Visit the steps documentation for details on defining steps.

action[].toggle_functions

object[]

Whether to toggle the functions on or off.

See toggle_functions for additional details.

toggle_functions[].active

boolean

Default: true

Whether to activate or deactivate the functions.

toggle_functions[].function

object[]

A list of functions to toggle.

action[].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.

action[].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.

See set_meta_data for additional details.

action[].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.

action[].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.

action[].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

Default: false

Whether to wait for the audio file to finish playing before continuing.

action[].stop_playback_bg

boolean

Whether to stop the background audio file.

action[].user_input

string

Used to inject text into the users queue as if they input the data themselves.

action[].context_switch

object

A JSON object containing the context to switch to.

See context_switch for additional details.

context_switch.system_prompt

string

The instructions to send to the agent.

context_switch.consolidate

boolean

Default: 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."
                                }
                              }
                            ]
                          }
                        }
                      }
                    ]
                  }
                }
              }
            ]
          }
        }
      }
    ]
  }
}