ai

Creates an AI agent that conducts voice conversations using automatic speech recognition (ASR), large language models (LLMs), and text-to-speech (TTS) synthesis. The agent processes caller speech in real-time, generates contextually appropriate responses, and can execute custom functions to interact with external systems and databases through SignalWire AI Gateway (SWAIG).

Since the prompt configuration is central to AI agent behavior, it is recommended to read the Prompting Best Practices guide.

ai

objectrequired

An object that defines an AI agent for conducting voice conversations. Accepts the ai parameters listed below to configure the agent's prompt, behavior, functions, language support, and other settings.

ai Parameters

ai.prompt

objectrequired

Defines the AI agent's personality, goals, behaviors, and instructions for handling conversations. The prompt establishes how the agent should interact with callers, what information it should gather, and how it should respond to various scenarios.

It is recommended to write prompts using markdown formatting as LLMs better understand structured content. Additionally it is recommended to read the Prompting Best Practices guide.

ai.global_data

object

A key-value object for storing data that persists throughout the AI session. Can be set initially in the SWML script or modified during the conversation using the set_global_data action.

The global_data object is accessible everywhere in the AI session: prompts, AI parameters, and SWML returned from SWAIG functions. Access properties using template strings (e.g ${global_data.property_name})

ai.hints

string

Hints help the AI agent understand certain words or phrases better. Words that can commonly be misinterpreted can be added to the hints to help the AI speak more accurately.

See hints for more details.

ai.languages

object[]

An array of JSON objects defining supported languages in the conversation.

See languages for more details.

ai.params

object

A JSON object containing parameters as key-value pairs.

See params for more details.

ai.post_prompt

object

The final set of instructions and configuration settings to send to the agent.

See post_prompt for more details.

ai.post_prompt_url

string

The URL to which to send status callbacks and reports. Authentication can also be set in the url in the format of username:password@url.

See post_prompt_url for more details.

ai.pronounce

object[]

An array of JSON objects to clarify the AI's pronunciation of words or expressions.

See pronounce for more details.

ai.SWAIG

object

An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue.

See SWAIG for more details.

Example

Minimal AI agent configuration:

YAML

version: 1.0.0
sections:
  main:
    - answer: {}
    - ai:
        prompt:
          text: "You are a customer service agent. Answer questions about account status and billing."

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "answer": {}
      },
      {
        "ai": {
          "prompt": {
            "text": "You are a customer service agent. Answer questions about account status and billing."
          }
        }
      }
    ]
  }
}