Skip to main content

ai

Connect to an AI Agent.

Parameters​

NameTypeDescription
promptobjectThe initial set of instructions and settings to configure the agent. Optional. Default is not set. See prompt parameters below.
post_promptobjectThe final set of instructions and configuration settings to send to the agent. Optional. Default is not set. See post_prompt parameters below.
post_prompt_urlstringURL to send status callbacks and reports to. Optional. Default is not set. See Callback Parameters for details on the request body.
post_prompt_auth_userstringAuth username for post_url endpoint. Optional. Default is not set.
post_prompt_auth_passwordstringAuth password for post_url endpoint. Optional. Default is not set.
paramsobjectA JSON object containing parameters as key-value pairs. For the full list of params for possible values. Optional. Default is undefined.
SWAIGobject[]An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue. Optional. Default is not set.
hintsstring[]An array of hints (as strings) to provide context to the dialogue. Optional. Default is not set.
languagesobject[]An array of JSON objects defining supported languages in the conversation. Optional. Default is "en-us".
pronounceobject[]An array of JSON objects to clarify the AI's pronunciation of words or expressions. Optional. Default is not set. The fields of this object are the three following.
pronounce.replacestringThe expression to replace. Required.
pronounce.withstringThe phonetic spelling of the expression. Required.
pronounce.ignore_casebooleanWhether the pronunciation replacement should ignore case. Optional. Default is true.

Parameters for prompt and post_prompt​

NameTypeDescription
textstringThe instructions to send to the agent. Optional. Default is not set.
temperaturenumberRandomness setting. Float value between 0.0 and 1.5. Closer to 0 will make the output less random. Optional. Default is 1.0.
top_pnumberRandomness setting. Alternative to temperature. Float value between 0.0 and 1.0. Closer to 0 will make the output less random. Optional. Default is 1.0.
confidencenumberThreshold to fire a speech-detect event at the end of the utterance. Float value between 0.0 and 1.0. Decreasing this value will reduce the pause after the user speaks, but may introduce false positives. Optional. Default is 0.6.
presence_penaltynumberAversion to staying on topic. Float value between -2.0 and 2.0. Positive values increase the model's likelihood to talk about new topics. Optional. Default is 0.
frequency_penaltynumberAversion to repeating lines. Float value between -2.0 and 2.0. Positive values decrease the model's likelihood to repeat the same line verbatim. Optional. Default is 0.

Parameters for SWAIG​

NameTypeDescription
defaultsobjectDefault settings for all SWAIG functions. If defaults is not set, settings may be set in each function object. Optional. Default is not set.
defaults.web_hook_urlstringDefault URL to send status callbacks and reports to. Optional. Default is not set. See Callback Parameters for details on the request body.
defaults.web_hook_auth_userstringDefault auth username for web_hook_url endpoint. Optional. Default is not set.
defaults.web_hook_auth_passwordstringDefault auth password for web_hook_url endpoint. Optional. Default is not set.
native_functionsstring[]Prebuilt functions the AI agent is able to call.
includesobject[]An array of objects to include remote function signatures. The object fields are url to specify where the remote functions are defined and functions which is an array of the function names as strings. See examples below of implementation.
functionsobject[]An array of JSON objects to define functions that can be executed during the interaction with the AI. Optional. Default is not set. The fields of this object are the six following.
functions.activebooleanWhether the function is active. Optional. Default is true.
functions.functionstringA unique name for the function. For example, "get_weather". Required.
functions.meta_dataobjectA JSON object containing any metadata, as a key-value map. Optional. Default is not set.
functions.meta_data_tokenstringScoping token for meta_data. If not supplied, metadata will be scoped to function's web_hook_url. Optional. Default is set by SignalWire.
functions.data_mapobject[]An object containing properties to process or validate the input, perform actions based on the input, or connect to external APIs or services in a serverless fashion.
functions.web_hook_urlstringFunction-specific URL to send status callbacks and reports to. Takes precedence over a default setting. Optional. Default is not set. See Callback Parameters for details on the request body.
functions.web_hook_auth_userstringFunction-specific auth username for web_hook_url endpoint. Takes precedence over a default setting. Optional. Default is not set.
functions.web_hook_auth_passstringFunction-specific auth password for web_hook_url endpoint. Takes precedence over a default setting. Optional. Default is not set.
functions.purposestringA description of the context and purpose of the function, to explain to the agent when to use it. Required.
functions.argumentobjectA JSON object defining the input that should be passed to the function. The fields of this object are the following two parameters. Required.
functions.argument.typestringThe type of argument the AI is passing to the function. Possible values are "string" and "object". Required.
functions.argument.propertiesobjectA JSON object describing the argument. The value is set by the user. For example, "location" for a location-based search or "company" if searching a database of companies. This object has sub-parameters description and type to help define the property. See examples below for implementation. Required.

Parameters for native_functions​

NameTypeDescription
check_timestringReturns the time in a location specified by the caller.
wait_secondsstringTracks a certain amount of time they need to wait, as specified in the prompt or by a caller.

Parameters for data_map​

NameTypeDescription
data_map.expressionsobject[]An array of objects that define patterns and corresponding actions.
data_map.expressions.stringstringThe actual input or value from the user or system.
data_map.expressions.patternstringA regular expression pattern to validate or match the string.
data_map.expressions.outputobjectDefines the response or action to be taken when the pattern matches.
data_map.expressions.output.responsestringA static response text or message.
data_map.expressions.output.actionobject[]A list of actions to be performed upon matching.
data_map.webhooksobject[]An array of objects that define external API calls.
data_map.webhooks.urlstringThe endpoint for the external service or API.
data_map.webhooks.headersobjectAny necessary headers for the API call.
data_map.webhooks.methodstringThe HTTP method (GET, POST, etc.) for the API call.
data_map.webhooks.outputobjectDefines the format or structure of the response from the API.
data_map.webhooks.output.actionobject[]A list of actions to be performed upon matching.
data_map.webhooks.output.responsestringA static response text or message based on the outcome of the API call.

Valid actions for output.action​

NameTypeDescription
SWMLobjectA SWML object to be executed.
saystringA message to be spoken by the AI agent.
stopbooleanWhether to stop the conversation.
toggle_functionsobject[]Whether to toggle the functions on or off.
toggle_functions.activebooleanWhether to activate or deactivate the functions. Default is true
toggle_functions.functionobject[]A list of functions to toggle.
back_to_back_functionsbooleanWhether to execute functions back to back. Default is false
set_meta_dataobjectA JSON object containing any metadata, as a key-value map.
playback_bgobjectA JSON object containing the audio file to play.
playback_bg.filestringURL or filepath of the audio file to play.
playback_bg.waitbooleanWhether to wait for the audio file to finish playing before continuing. Default is false
stop_playback_bgbooleanWhether to stop the background audio file.
user_inputstringused to inject text into the users queue as if they input the data themselves.
context_switchobjectA JSON object containing the context to switch to. Default is not set.
context_switch.system_promptstringThe instructions to send to the agent. Default is not set.
context_switch.consolidatebooleanWhether to consolidate the context. Default is false
context_switch.user_promptstringA 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. Default is not set

Parameters for languages​

If changing the language from the default, all three parameters are required for a valid entry.

NameTypeDescription
namestringName of the language. For example, "French". Optional. Default is "English".
codestringLanguage code. For example, "fr-FR". Optional. Default is "en-us".
List of language codes can be found here: Google Codes
voicestringVoice to use for the language. For example, "fr-FR-Neural2-B". Optional. Default is picked by SignalWire.
List of language voices can be found here Google Voices
fillersstring[]An array of strings to be used as fillers in the conversation. Optional. Default is not set.
enginestringThe engine to use for the language. For example, "elevenlabs". Optional. Default is "gcloud".

Callback Request Parameters​

Request Parameters for post_prompt_url​

SignalWire will make a request to the post_prompt_url with the following parameters:

NameTypeDescription
actionstringAction that prompted this request. The value will be "post_conversation".
ai_end_datenumberTimestamp indicating when the AI session ended.
ai_session_idstringA unique identifier for the AI session.
ai_start_datenumberTimestamp indicating when the AI session started.
app_namestringName of the application that originated the request.
call_answer_datenumberTimestamp indicating when the call was answered.
call_end_datenumberTimestamp indicating when the call ended.
call_idstringID of the call.
call_logobjectThe complete log of the call, as a JSON object.
call_log.contentstringContent of the call log entry.
call_log.rolestringRole associated with the call log entry (e.g., "system", "assistant", "user").
call_start_datenumberTimestamp indicating when the call started.
caller_id_namestringName associated with the caller ID.
caller_id_numberstringNumber associated with the caller ID.
content_dispositionstringDisposition of the content.
content_typestringType of content. The value will be text/swaig.
post_prompt_dataobjectThe answer from the AI agent to the post_prompt. The object contains the three following fields.
post_prompt_data.parsedobjectIf a JSON object is detected within the answer, it is parsed and provided here.
post_prompt_data.rawstringThe raw data answer from the AI agent.
post_prompt_data.substitutedstringThe answer from the AI agent, excluding any JSON.
project_idstringID of the project.
space_idstringID of the space.
SWMLVarsobjectA collection of variables related to SWML.
swaig_logobjectA log related to SWAIG functions.
total_input_tokensnumberRepresents the total number of input tokens.
total_output_tokensnumberRepresents the total number of output tokens.
versionstringVersion number.

Post Prompt Callback Request Example​

Below is a json example of the callback request that is sent to the post_prompt_url:

{
   "total_output_tokens": 119,
   "caller_id_name": "[CALLER_NAME]",
   "SWMLVars": {
      "ai_result" : "success",
      "answer_result" : "success"
   },
   "call_start_date": 1694541295773508,
   "project_id": "[PROJECT_ID]",
   "call_log": [
      {
         "content": "[AI INITIAL PROMPT/INSTRUCTIONS]",
         "role": "system"
      },
      {

         "content": "[AI RESPONSE]",
         "role": "assistant"
      },
      {
         "content": "[USER RESPONSE]",
         "role": "user"
      }
   ],
   "ai_start_date": 1694541297950440,
   "call_answer_date": 1694541296799504,
   "version": "2.0",
   "content_disposition": "Conversation Log",
   "conversation_id": "[CONVERSATION_ID]",
   "space_id": "[SPACE_ID]",
   "app_name": "swml app",
   "swaig_log": [
      {
         "post_data": {
            "content_disposition": "SWAIG Function",
            "conversation_id": "[CONVERSATION_ID]",
            "space_id": "[SPACE_ID]",
            "meta_data_token": "[META_DATA_TOKEN]",
            "app_name": "swml app",
            "meta_data": {},
            "argument": {
               "raw": "{\n  \"target\": \"[TRANSFER_TARGET]\"\n}",
               "substituted": "",
               "parsed": [
                  {
                     "target": "[TRANSFER_TARGET]"
                  }
               ]
            },
            "call_id": "[CALL_ID]",
            "content_type": "text/swaig",
            "ai_session_id": "[AI_SESSION_ID]",
            "caller_id_num": "[CALLER_NUMBER]",
            "caller_id_name": "[CALLER_NAME]",
            "project_id": "[PROJECT_ID]",
            "purpose": "Use to transfer to a target",
            "argument_desc": {
               "type": "object",
               "properties": {
                  "target": {
                     "description": "the target to transfer to",
                     "type": "string"
                  }
               }
            },
            "function": "transfer",
            "version": "2.0"
         },
         "command_name": "transfer",
         "epoch_time": 1694541334,
         "command_arg": "{\n  \"target\": \"[TRANSFER_TARGET]\"\n}",
         "url": "https://example.com/here",
         "post_response": {
            "action": [
               {
                  "say": "This is a say message!"
               },
               {
                  "SWML": {
                     "sections": {
                        "main": [
                           {
                              "connect": {
                                 "to": "+1XXXXXXXXXX"
                              }
                           }
                        ]
                     },
                     "version": "1.0.0"
                  }
               },
               {
                  "stop": true
               }
            ],
            "response": "transferred to [TRANSFER_TARGET], the call has ended"
         }
      }
   ],
   "total_input_tokens": 5627,
   "caller_id_num": "[CALLER_NUMBER]",
   "call_id": "[CALL_ID]",
   "call_end_date": 1694541335435503,
   "content_type": "text/swaig",
   "action": "post_conversation",
   "post_prompt_data": {
      "substituted": "[SUMMARY_MESSAGE_PLACEHOLDER]",
      "parsed": [],
      "raw": "[SUMMARY_MESSAGE_PLACEHOLDER]"
   },
   "ai_end_date": 1694541335425164,
   "ai_session_id": "[AI_SESSION_ID]"
}

Responding to Post Prompt Requests​

The response to the callback request should be a JSON object with the following parameters:

{
  "response": "ok"
}

Request Parameters for web_hook_url​

SignalWire will make a request to the web_hook_url of a SWAIG function with the following parameters:

NameTypeDescription
content_typestringType of content. The value will be text/swaig.
app_namestringName of the application that originated the request.
functionstringName of the function that was invoked.
meta_dataobjectA JSON object containing any user metadata, as a key-value map.
SWMLVarsobjectA collection of variables related to SWML.
purposestringThe purpose of the function being invoked. The value will be the functions.purpose value you provided in the SWAIG parameters.
argument_descstring | objectThe description of the argument being passed. This value comes from the argument you provided in the SWAIG parameters.
argumentobjectThe argument the AI agent is providing to the function. The object contains the three following fields.
argument.parsedobjectIf a JSON object is detected within the argument, it is parsed and provided here.
argument.rawstringThe raw argument provided by the AI agent.
argument.substitutedstringThe argument provided by the AI agent, excluding any JSON.
versionstringVersion number.

Webhook Request Example​

Below is a json example of the callback request that is sent to the web_hook_url:

{
  "app_name": "swml app",
  "function": "get_weather",
  "version": "2.0",
  "content_type": "text/swaig",
  "content_disposition": "SWAIG Function",
  "channel_active": true,

  "caller_id_name": "[CALLER_ID]",
  "caller_id_num": "[CALLER_NUMBER]",

  "project_id": "[PROJECT_ID]",
  "space_id": "[SPACE_ID]",
  "call_id": "[CALL_ID]",
  "ai_session_id": "[AI_SESSION_ID]",

  "purpose": "To determine what the current weather is in a provided location.",
  "meta_data_token": "[TOKEN]",
  "meta_data": {},

  "argument": {
    "parsed": [
      {
        "location": "[USER_INPUT]"
      }
    ],
    "raw": "{\n  \"location\": \"[USER_INPUT]\"\n}",
    "substituted": ""
  },

  "argument_desc": {
    "properties": {
      "location": {
        "type": "string",
        "description": "The location to get the weather for"
      }
    },
    "type": "object"
  }
}

Responding to Webhook Requests​

The response should be in JSON format, the primary key that the AI will look for is the response key. The value associated with this key will be the content or instruction that the AI will process.

{
  "response": "The weather in [CITY] is [WEATHER]."
}

Variables​

  • ai_result: (out) success | failed
  • return_value: (out) success | failed

Examples​

A Voicemail Bot​

---
version: 1.0.0
sections:
  main:
    - label: ai
      ai:
        post_prompt_url: https://example.com/my-api
        prompt:
          confidence: 0.6
          temperature: 0.2
          text: |
            You are Franklin's assistant, and your job is to collect messages for him over the phone.
            You can reassure that Franklin will get in touch as soon as possible.
            Collect the user's name and number if you do not already know it from the caller id.
            Start by presenting yourself, then let the contact know that Franklin is not available, then offer to collect a message.
            After collecting the message, do not wait for the user to end the conversation: say good bye and hang up the call.
        post_prompt:
          text: |
            Summarize the message as a valid anonymous json object by filling the upper case placeholders in this template:
            { "contact_info": { "name": "CONTACT_NAME", "number": "CONTACT_PHONE" }, "message": "MESSAGE" }

Declaring functions​

version: 1.0.0
sections:
  main:
    - ai:
        post_prompt_url: "https://example.com/my-api"
        prompt:
          text: |
            You are a helpful assistant that can provide information to users about a destination. You can use the appropriate function to get the phone number, address, or weather information.
        post_prompt:
          text: "Summarize the conversation."
        SWAIG:
          includes:
            - functions:
                - get_phone_number
                - get_address
              url: https://example.com/functions
              user: me
              pass: secret
          defaults:
            web_hook_url: https://example.com/my-webhook
            web_hook_auth_user: me
            web_hook_auth_pass: secret
          functions:
            - function: get_weather
              purpose: To determine what the current weather is in a provided location.
              argument:
                properties:
                  location:
                    type: string
                    description: The name of the city to find the weather from.
                type: object

Executing SWML from a SWAIG function​

SWAIG functions allow you to execute SWML from within itself. This allows you to create a function that can be used to execute a specific SWML block, that lives outside the AI language model. The benefit of this is you can get more granular control over the execution of what happens next after the function is triggered while also getting the additional benefits of SignalWire's APIs.

For this example, we will create an AI and who will help assist with transferring the call. The AI will ask the user for a destination to transfer to, and then execute a function to send an SMS to notify the destination that they have a call coming in, and then transfer the call.

Enabling SWML Execution​

The first important step is to make sure our AI is capable of executing SWML in its functions. In the ai.params, you will need to set the parameter swaig_allow_swml to true, to allow SWML execution:

params:
  swaig_allow_swml: true

Data Map Example​

In this example, we are using the data_map to execute SWML in the data_map.expressions.output.action.

Creating the Function​

We will create a function that will send an SMS to the destination number, and then transfer the call to the destination number.

SWAIG:
  functions:
    - function: transfer
      purpose: Get input from user and transfer to a destination department
      argument:
        type: object
        properties:
          destination:
            type: string
            description: The destination to transfer to
      data_map:
        expressions:
          - string: '${args.destination}'
            pattern: .*
            output:
              response: Transferring call.
              action:
                - SWML:
                    sections:
                      main:
                        - send_sms:
                            to_number: '+1XXXXXXXXXX'
                            from_number: '+1YYYYYYYYYY'
                            body: 'Call coming from ${caller_id_num}'
                        - connect:
                            to: '+1XXXXXXXXXX'
                - stop: true
SWML Execution​

We are using the SWML action to execute the SWML block that will send the SMS using the send_sms method and then connect the call to the destination number using the connect method.

action:
- SWML:
    sections:
      main:
      - send_sms:
          to_number: '+1XXXXXXXXXX'
          from_number: '+1YYYYYYYYYY'
          body: Call coming from ${caller_id_num}
      - connect:
          to: '+1XXXXXXXXXX'
Full Example​
sections:
  main:
  - ai:
      prompt:
        text: |-
          Your name is Frank. You help the user with transferring calls.
          ## Handling The User
          - You are asked to transfer a call.
          - You ask for the destination.
          - You use the 'transfer' function to transfer the call.
      post_prompt_url: https://example.com/post_prompt_url
      params:
        swaig_allow_swml: true
      SWAIG:
        functions:
        - function: transfer
          purpose: Get input from user and transfer to a destination department
          argument:
            type: object
            properties:
              destination:
                type: string
                description: The destination to transfer to
          data_map:
            expressions:
            - string: ${args.destination}
              pattern: .*
              output:
                response: Transferring call.
                action:
                - SWML:
                    sections:
                      main:
                      - send_sms:
                          to_number: '+1XXXXXXXXXX'
                          from_number: '+1YYYYYYYYYY'
                          body: Call coming from ${caller_id_num}
                      - connect:
                          to: '+1XXXXXXXXXX'
                - stop: true
      hints:
      - transfer

Webhook Example​

In this example, we are using the function.web_hook_url to execute SWML.

Creating the Function​

We will create a function that will take the input from the user as an argument (destination) and then make a request to the function.web_hook_url.

SWAIG:
  functions:
    - function: transfer
      web_hook_url: 'https://example.com/transfer'
      purpose: Get input from user and transfer to a destination department
      argument:
        type: object
        properties:
          destination:
            type: string
            description: The destination to transfer to
SWML Execution​

When executing SWML while utilizing a function.web_hook_url, you will need to provide a response from the function.web_hook_url that contains the action key. In this action key you will need to provide the SWML block that you want to execute.

Format:

{
"response": "The response to the AI",
"action": ["The SWML block to execute"]
}

Webhook Response Example:

We are using the SWML action to execute the SWML block that will send the SMS using the send_sms method and then connect the call to the destination number using the connect method.

{
  "response": "Transferring call.",
  "action": [
    {
      "SWML": {
        "sections": {
          "main": [
            {
              "send_sms": {
                "to_number": "+1XXXXXXXXXX",
                "from_number": "+1YYYYYYYYYY",
                "body": "Call coming from ${caller_id_num}"
              }
            },
            {
              "connect": {
                "to": "+1XXXXXXXXXX"
              }
            }
          ]
        }
      }
    }
  ]
}
Full Example​
sections:
  main:
  - ai:
      prompt:
        text: |-
          Your name is Frank. You help the user with transferring calls.
          ## Handling The User
          - You are asked to transfer a call.
          - You ask for the destination.
          - You use the 'transfer' function to transfer the call.
      post_prompt_url: https://example.com/post_prompt_url
      params:
        swaig_allow_swml: true
      SWAIG:
        functions:
        - function: transfer
          web_hook_url: https://example.com/transfer
          purpose: Get input from user and transfer to a destination department
          argument:
            type: object
            properties:
              destination:
                type: string
                description: The destination to transfer to
      hints:
      - transfer

data_map Examples​

Webhook Example for Transfer​

In this example, the system aims to transfer a call based on a provided target by querying an external service via a webhook. This allows for dynamic decision-making based on real-time or externally managed data.

Example:

sections:
  main:
  - ai:
      prompt:
        text: Your name is Frank. You help transfer to the right department.
      post_prompt: Summarize the call as a json object
      post_prompt_url: https://example.com/here
      SWAIG:
        functions:
        - function: transfer
          purpose: use to transfer to a target
          argument:
            type: object
            properties:
              target:
                type: string
                description: The target to transfer to
          data_map:
            webhooks:
            - url: https://example.com/v1/destination?name=${enc:args.target}
              headers:
                X-Api-Key: api-token-here
              method: GET
              output:
                response: Transferring to ${input.args.target}.
                action:
                - SWML:
                    version: 1.0.0
                    sections:
                      main:
                      - connect:
                          to: ${destination_number}
                  stop: true
Responding to the Webhook request​

You can learn more on how to respond to a webhook request here.

In this example we will pass an additional parameter destination_number which will be used to connect the call to the destination number.

{
  "response": "Transferring to ${input.args.target}.",
  "destination_number": "+1XXXXXXXXXX"
}
Expressions Example for Transfer:​

In this example, the AI aims to transfer a call based on a provided target name. Instead of querying an external service (like the webhook scenario), this approach utilizes a predefined list meta_data to determine the destination of the transfer.

The meta_data.table serves as a directory, linking user-friendly targets (like "support" or "sales") to distinct phone numbers. When a user provides input, the system uses the pattern \\w+ to see if the input corresponds with any keys in this table. If there's a match, the system retrieves the associated phone number and initiates the call transfer to that destination. However, if the input doesn't match any key, the system resorts to the fallback expression ".*" to capture all other inputs, subsequently informing the user that the intended transfer was unsuccessful.

Example:

sections:
  main:
  - ai:
      prompt:
        text: Your name is Frank. You help transfer to the right department.
      post_prompt: Summarize the call as a json object
      post_prompt_url: https://example.com/post_prompt_url
      SWAIG:
        functions:
        - function: transfer
          purpose: use to transfer to a target
          data_map:
            expressions:
            - pattern: \\w+
              string: ${meta_data.table.${lc:args.target}}
              output:
                action:
                - say: Please stand by while I connect your call.
                - SWML:
                    version: 1.0.0
                    sections:
                      main:
                      - connect:
                          from: '+1XXXXXXXXXX'
                          to: ${meta_data.table.${lc:args.target}}
                - stop: true
                response: transferred, the call has ended.
            - string: ${args.target}
              pattern: .*
              output:
                response: I'm sorry, I was unable to transfer your call to ${input.args.target}.
          argument:
            type: object
            properties:
              target:
                description: the target to transfer to
                type: string
          meta_data:
            table:
              support: '+1XXXXXXXXXX'
              sales: '+1YYYYYYYYYY'

toggle_functions Example​

In this example, the transfer function is toggled off from the start. The AI agent will toggle this function on after the get_joke function is called. This creates a scenario where a user can only be transferred after hearing a joke from the AI. The AI agent will then match the transfer destination based on the user's input, with the meta_data table serving as a directory for the transfer destinations. If no match is found, the AI agent will fall back to the ".*" expression, which will inform the user that the transfer was unsuccessful and requires a valid input.

transfer Function​

      SWAIG:
        functions:
        - function: transfer
          active: 'false'
          purpose: use to transfer to a target
          argument:
            type: object
            properties:
              target:
                description: the target to transfer to
                type: string
          data_map:
            expressions:
            - pattern: "\\w+"
              string: "${meta_data.table.${lc:args.target}}"
              output:
                action:
                - say: Please stand by while I connect your call.
                - SWML:
                    version: 1.0.0
                    sections:
                      main:
                      - connect:
                          to: "${meta_data.table.${lc:args.target}}"
                - stop: 'true'
                response: transferred, the call has ended.
            - string: "${args.target}"
              pattern: ".*"
              output:
                response: I'm sorry, I was unable to transfer your call to ${input.args.target}.
          meta_data:
            table:
              support: "+1XXXXXXXXXX"
              sales: "+1YYYYYYYYYY"

We set the function to being toggled off with the following line:

active: 'false'

get_joke Function​

        - function: get_joke
          purpose: use to get a joke
          data_map:
            webhooks:
            - url: https://example.com/v1/${args.type}
              headers:
                X-Api-Key: api-token-here
              method: GET
              output:
                response: 'Tell the user: ${array[0].joke}.' # array[0] is the first joke in the array
                action:
                - toggle_functions:
                    active: 'true'
                    function: transfer

In the above function, we set the transfer function to be toggled on. Now when a user asks to be transferred, the AI agent will now be able to do so because the transfer function is toggled on.

- toggle_functions:
    active: 'true'
    function: transfer

Full example​

sections:
  main:
  - ai:
      prompt:
        text: Your name is Frank. You help transfer to the right department. Use the 'get_joke' function to get a joke.
      post_prompt: Summarize the call as a json object
      post_prompt_url: https://example.com/post_prompt_url
      SWAIG:
        functions:
        - function: transfer
          active: 'false'
          purpose: use to transfer to a target
          argument:
            type: object
            properties:
              target:
                description: the target to transfer to
                type: string
          data_map:
            expressions:
            - pattern: "\\w+"
              string: "${meta_data.table.${lc:args.target}}"
              output:
                action:
                - say: Please stand by while I connect your call.
                - SWML:
                    version: 1.0.0
                    sections:
                      main:
                      - connect:
                          to: "${meta_data.table.${lc:args.target}}"
                - stop: 'true'
                response: transferred, the call has ended.
            - string: "${args.target}"
              pattern: ".*"
              output:
                response: I'm sorry, I was unable to transfer your call to ${input.args.target}.
          meta_data:
            table:
              support: "+1XXXXXXXXXX"
              sales: "+1YYYYYYYYYY" # These are the numbers that will be used to transfer the call


        - function: get_joke
          purpose: used to get a joke
          argument:
            type: object
            properties:
              type:
                type: string
                description: must either be 'jokes' or 'dadjokes'
          data_map:
            webhooks:
            - url: https://example.com/v1/${args.type}
              headers:
                X-Api-Key: API TOKEN HERE
              method: GET
              output:
                response: 'Tell the user: ${array[0].joke}.' # array[0] is the first joke in the array
                action:
                  - toggle_functions:
                      - active: 'true'
                        function: transfer

set_meta_data Example​

In this example, we demonstrate how to use set_meta_data to store information to reference later. The AI agent, will store a user's name and then look up any additional stored information.

The benefit of storing information in meta_data is that the information it can be referenced from any function with the same meta_data_token, while also never being exposing the information to the language model. This allows for the AI agent to store sensitive information without the risk of it being exposed to the AI agent.

1. Storing User Information​

The store_user function is used to store the user's name. The user's name and a secret associated with them are stored as meta_data.

- function: store_user
  purpose: Store the user information
  argument:
    type: object
    properties:
      name:
        type: string
        description: The name of the user
  data_map:
    webhooks:
    - url: https://example.com/name_bank?name=${lc:args.name}
      method: GET
      output:
        response: The user information was stored. User information can now be looked up with the "get_user_info" function.
        action:
        - set_meta_data:
            ${lc:input.args.name}: ${Records[0].secret}
        - back_to_back_functions: true
        - toggle_functions:
          - active: true
            function: get_user_info
        - say: Your info was stored.
  meta_data_token: example_token

This will send a request to data_map.webhooks.url with the user's name as a query parameter. In this example, we have our server responding with a Records array in the response. This will contain information on the user.

Server Response:

{
"response": "The user information was stored.",
"Records": [{"secret": ["Info about user here"]}]
}

Once the response has returned from the webhook, the meta_data will be set using set_meta_data in the data_map.webhooks.output.action of the function, the get_user_info function will be toggled on using toggle_functions, and the user will be notified that their information was stored.

The meta_data key is set to the users name and the value is set to the first value in the Records array.

- set_meta_data:
    ${lc:input.args.name}: ${Records[0].secret}

2. Looking up User Information​

After storing the user information in meta_data, we can now look up the user information with the get_user_info function.

- function: get_user_info
  purpose: lookup user information
  argument:
    type: object
    properties:
      name:
        type: string
        description: The name of the user
  data_map:
    expressions:
    - string: ${lc:args.name}
      pattern: /\\w+/i
      output:
        response: The meta_data is valid.
        action:
        - say: Your info is ${meta_data.${lc:args.name}}
        - stop: true
    - string: .*
      pattern: .*
      output:
        response: The meta_data is invalid. User has not been told their information.
  active: false
  meta_data_token: example_token

This function will check if the meta_data is valid by checking if the user's name is a key in the meta_data object. If the meta_data is valid, the user will be told their information. If the meta_data is invalid, the user will be told that their information has not been stored.

Full Example​

sections:
  main:
  - ai:
      prompt:
        text: >-
          Your name is Mr. Blabbermouth. You help the user.
          ## Handling The User
          - You are asked to store a user's information.
            - You ask for their name.
          - You use the 'store_user' function to store the users name.
          ### Looking up user information
          - You can only look up a users information after storing it.
      post_prompt:
        text: Summarize the call in JSON format.
        temperature: 0.1
        top_p: 0.1
      post_prompt_url: https://example.com/post_prompt_url
      params:
        swaig_allow_swml: true
      SWAIG:
        functions:
        - function: store_user
          purpose: Store the user information
          argument:
            type: object
            properties:
              name:
                type: string
                description: The name of the user
          data_map:
            webhooks:
            - url: https://example/name_bank?name=${lc:args.name}
              method: GET
              output:
                response: The user information was stored. User information can now
                  be looked up with the "get_user_info" function.
                action:
                - set_meta_data:
                    ${lc:input.args.name}: ${Records[0].secret}
                - back_to_back_functions: true
                - toggle_functions:
                  - active: true
                    function: get_user_info
                - say: Your info was stored.
          meta_data_token: example_token
        - function: get_user_info
          purpose: lookup user information
          argument:
            type: object
            properties:
              name:
                type: string
                description: The name of the user
          data_map:
            expressions:
            - string: ${lc:args.name}
              pattern: /\w+/i
              output:
                response: The meta_data is valid. User has already been told their
                  information. Do no repeat it.
                action:
                - say: Your info is ${meta_data.${lc:args.name}}
                - stop: true
            - string: /.*/
              pattern: /.*/
              output:
                response: The meta_data is invalid. User has not been told their information.
          active: 'false'
          meta_data_token: example_token

switch_context Example​

In this example, we will demonstrate how to use switch_context to shift the focus of the conversation. The AI agent will switch between a StarWars and StarTrek context. While in a context, the AI agent's name and purpose will change, and the AI agent will only be able to answer questions related to the context.

Initial Prompt​

caution

Providing too much information in the initial prompt can cause the AI agent to get confused during a context switch. It is recommended to keep the initial prompt short and simple. Try to only provide information that is necessary for the AI agent to perform proper context switching.

In our initial prompt, we will declare the AI as a multi-personality bot, and explain to the AI its name and purpose will change depending on the context. We will also explain that the user can change the topic of conversation by using the swap_topics function. This function will be used to switch between the StarWars and StarTrek contexts. Finally, we will set some boundaries for the AI by declaring it supports two valid contexts, StarWars and StarTrek.

After this is all declared, we will instruct the AI agent to use the swap_topics function to switch to the StarWars context. This will cause the AI agent to start the call in the StarWars context.

sections:
  main:
  - ai:
      prompt:
        text: |
          You are a multi-personality bot.
          You support two valid contexts. 'Star Wars' and 'Star Trek.'
          The context dictates your name and purpose.
          If the user asks about changing topics, use the `swap_topics` function.

          To begin, use the 'swap_topics` function to switch to 'Star Wars'.

Context Switching​

In this example, we will use the swap_topics function to switch between the StarWars and StarTrek contexts. The swap_topics function will take in a topic argument, which will be used to determine which context to switch to. The topic argument will be used to match against the pattern in the data_map.expressions array. If a match is found, the output.action will be executed. If no match is found, we will fall back to the ".*" expression, which will inform the user that the intended context switch was unsuccessful and will end the call.

Example Function:

        - function: swap_topics
          purpose: To change topics.
          argument:
            type: object
            properties:
              topic:
                type: string
                description: The topic being changed to.
          data_map:
            expressions:
            - string: ${lc:args.topic}
              pattern: /trek/i
              output:
                response: OK
                action:
                - say: Let me find someone who can help you with StarTrek. Please
                    hold.
                - context_switch: ...
            - string: ${lc:args.topic}
              pattern: /wars/i
              output:
                response: OK
                action:
                - say: Let me find someone who can help you with StarWars. Please
                    hold.
                - context_switch: ...
            - string: .*
              pattern: .*
              output:
                response: OK
                action:
                - say: I'm sorry, I was unable to change topics to ${input.args.topic}. End call.
                - stop: true
Context Switching Options​

In the data_map.expressions.output.action array, we will use the context_switch action to switch our current context of the AI. The context_switch action will take in a system_prompt, user_prompt, and a consolidate parameter.

  • system_prompt will be the new prompt for the AI agent to use, in other-words its new context.
  • user_prompt will be used as user input. It will tell the AI agent that it wants to talk about the new context.
  • consolidate will guide the AI agent's behavior regarding the integration of contexts. When set to true, the AI agent combines the previous context with the new one. If false, only the new context is considered.

StarWars Context​

In the StarWars context, the AI agent will be named Luke. The AI agent will only be able to answer questions related to StarWars. The user_prompt argument is set to I want to talk about StarWars. This will be used as user input. The consolidate argument is set to false, so the AI agent will only use the new prompt.

Example​
      - context_switch:
          system_prompt: |
            Your name is Luke. You are a bot that knows only about StarWars.
            ## Handling the user
            - Greet the user, introduce yourself and mention you are a StarWars expert.
            - Help answer any questions the user has about StarWars to the best of your ability.
          user_prompt: I want to talk about StarWars.
          consolidate: false

StarTrek Context​

In the StarTrek context, the AI agent will be named Leonard. The AI agent will only be able to answer questions related to StarTrek. The user_prompt argument is set to I want to talk about StarTrek. This will be used as user input. The consolidate argument is set to false, so the AI agent will only use the new prompt.

Example​
      - context_switch:
          system_prompt: |
            Your name is Leonard. You are a bot that knows only about StarTrek.
            ## Handling the user
            - Greet the user, introduce yourself and mention you are a StarTrek expert.
            - Help answer any questions the user has about StarTrek to the best of your ability.
          user_prompt: I want to talk about StarTrek.
          consolidate: false

Final Example​

caution

It's important to remember the boundaries of the AI agent that you have set in the initial prompt, and in the new context. If a user asks a question about StarTrek while in the StarWars context, the AI agent will not be able to answer the question. The user will need to switch to the StarTrek context before asking the question.

sections:
  main:
  - ai:
      prompt:
        text: |
          You are a multi-personality bot.
          You support two valid contexts. 'Star Wars' and 'Star Trek.'
          The context dictates your name and purpose.
          If the user asks about changing topics, use the `swap_topics` function.

          To begin, use the 'swap_topics` function to switch to 'Star Wars'.
      post_prompt_url: https://example.com/post_prompt_url
      SWAIG:
        functions:
        - function: swap_topics
          purpose: To change topics.
          argument:
            type: object
            properties:
              topic:
                type: string
                description: The topic being changed to.
          data_map:
            expressions:
            - string: ${lc:args.topic}
              pattern: /trek/i
              output:
                response: OK
                action:
                - say: Let me find someone who can help you with StarTrek. Please
                    hold.
                - context_switch:
                    system_prompt: |
                      Your name is Leonard. You are a bot that knows only about StarTrek.
                      ## Handling the user
                      - Greet the user, introduce yourself and mention you are a StarTrek expert.
                      - Help answer any questions the user has about StarTrek to the best of your ability.
                    user_prompt: I want to talk about StarTrek.
                    consolidate: false
            - string: ${lc:args.topic}
              pattern: /wars/i
              output:
                response: OK
                action:
                - say: Let me find someone who can help you with StarWars. Please
                    hold.
                - context_switch:
                    system_prompt: |
                      Your name is Luke. You are a bot that knows only about StarWars.
                      ## Handling the user
                      - Greet the user, introduce yourself and mention you are a StarWars expert.
                      - Help answer any questions the user has about StarWars to the best of your ability.
                    user_prompt: I want to talk about StarWars.
                    consolidate: false
            - string: ${lc:args.topic}
              pattern: .*
              output:
                response: OK
                action:
                - say: I'm sorry, I don't know anything about ${args.topic}. Ending
                    call.
                - stop: true
      hints:
      - StarWars
      - StarTrek
      - topic