ai | SignalWire

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 prompt engineering guide.

Properties

ai

objectRequired

An object that defines an AI agent for conducting voice conversations. Accepts the following properties to configure the agent’s prompt, behavior, functions, language support, and other settings.

ai.prompt

object

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. Required unless you set ai.agent instead.

It is recommended to write prompts using markdown formatting as LLMs better understand structured content. It is also recommended to read the prompt engineering guide.

ai.agent

string

The ID of an AI agent saved in your SignalWire Space, such as the agent_id of an AI agent created with the REST API. Use it instead of an inline configuration: the agent runs with its saved settings.

Set agent on its own. Other ai properties placed next to it are ignored. Don’t combine agent with prompt: if both are present, the inline configuration runs and agent is ignored.

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[] | object[]

An array of strings and objects that help the agent understand what the caller says. Hints don’t change how the agent speaks; to change pronunciation, use ai.pronounce.

Hints as strings: Each string is passed to speech recognition as a hint, making that word or phrase more likely to be recognized. Recognition isn’t guaranteed.

Hints as objects: Each object is a recognition hint (hint), a rewrite rule applied to the text the agent hears before the AI reads it (pattern with replace), or both.

One hint list covers every language the agent uses; there are no per-language hints. When speech recognition runs in code-switching mode, because ai.multilingual is set or a languages entry’s code is multi on Deepgram speech recognition, recognition hints are not used. That covers string entries and hint values, and no error is returned. Rewrite rules still apply to the transcript in every mode.

hints[].hint

string

A word or phrase passed to speech recognition as a hint, the same as a string entry. Required when pattern and replace are not set.

hints[].pattern

string

A regular expression matched against the text the agent hears. Set it together with replace; each match is replaced with replace before the AI reads the text.

hints[].replace

string

The text that replaces each match of pattern. Set it together with pattern.

hints[].ignore_case

booleanDefaults to false

If true, pattern is matched case-insensitively.

ai.languages

object[]

An array of JSON objects defining supported languages in the conversation. Mutually exclusive with ai.multilingual.

See languages for more details.

ai.multilingual

object

Configures a single agent to detect the caller’s language and answer in it, switching as the caller switches. Mutually exclusive with ai.languages: if both are set, ai.multilingual is used and ai.languages is ignored.

See multilingual 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. Set either text or pom for the instructions, the same way as in prompt.

post_prompt.text

string

The instructions to send to the agent, as a single block of text. Required unless pom is set.

post_prompt.pom

object[]

The instructions to send to the agent, as a Prompt Object Model (POM): an array of sections that SignalWire renders into a markdown document. Required unless text is set. Sections take the same properties as prompt.pom.

post_prompt.model

string

The AI model that writes the summary. When omitted, the agent’s model is used. If the model you name isn’t available, a default model is used instead; if no default model is available either, the agent doesn’t start.

post_prompt.max_tokens

integer

Limits the number of tokens the AI model may generate for the summary.

post_prompt.temperature

numberDefaults to 1.0

Randomness setting. Float value between 0.0 and 1.5. Closer to 0 will make the output less random.

post_prompt.top_p

numberDefaults to 1.0

Randomness setting. Alternative to temperature. Float value between 0.0 and 1.0. Closer to 0 will make the output less random.

post_prompt.confidence

numberDeprecated

Has no effect and can be omitted.

post_prompt.presence_penalty

numberDefaults to 0

Aversion to staying on topic. Float value between -2.0 and 2.0. Positive values increase the model’s likelihood to talk about new topics.

post_prompt.frequency_penalty

numberDefaults to 0

Aversion to repeating lines. Float value between -2.0 and 2.0. Positive values decrease the model’s likelihood to repeat the same line verbatim.

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 callback below.

ai.post_prompt_auth_user

string

The username for basic authentication on post_prompt_url. A username embedded in the URL takes precedence.

ai.post_prompt_auth_password

string

The password for basic authentication on post_prompt_url. A password embedded in the URL takes precedence.

ai.pronounce

object[]

An array of objects to clarify the AI’s pronunciation of certain words or expressions.

pronounce[].replace

stringRequired

The expression to replace.

pronounce[].with

stringRequired

The phonetic spelling of the expression.

pronounce[].ignore_case

booleanDefaults to false

Whether the pronunciation replacement should ignore case. Only the boolean true turns it on.

ai.SWAIG

object

An object that configures the functions the agent can call during the dialogue: user-defined functions, shared defaults, includes, native_functions, mcp_servers, and internal_fillers.

See SWAIG for more details.

ai.voice

string

The voice the agent speaks with when neither ai.languages nor ai.multilingual is set. Format: <engine id>.<voice id>, with an optional :<model id> suffix for engines that offer a choice of model, the same as languages[].voice. When ai.languages or ai.multilingual is set, the voices configured there are used instead.

Variables

ai_result: (out) success | failed. Whether the agent ran. failed also covers an agent value that isn’t a valid ID. When agent runs a saved agent, this method doesn’t set ai_result itself.

post_prompt_url callback

SignalWire sends the report to your post_prompt_url as an HTTP POST, signed with your project’s signing key so your endpoint can confirm it came from SignalWire. See Verify SWML request signatures.

Payload

{
  "content_type": "text/json",
  "content_disposition": "agent.summary",
  "conversation_type": "voice",
  "call_id": "2e1e66e5-5d07-413d-9668-55542992eec0",
  "app_name": "ai",
  "ai_session_id": "a0d4e6e5-5d07-413d-9668-55542992eec0",
  "action": "post_conversation"
}

See the AI post-prompt callback webhook page for the full field reference. To use the report for debugging and analysis, such as replaying the conversation, inspecting each SWAIG function call, or measuring latency, see Conversation analytics.

Responding to post prompt requests

Answer the end-of-call report with any 2xx status. The body is not read, so {"response": "ok"} is as good as an empty one.

The one request that does read your response is the conversation fetch, which arrives at the same URL with "action": "fetch_conversation" when the agent starts with a conversation_id and save_conversation enabled. Return the summary you stored for that conversation_id under a conversation_summary key, and the agent resumes with it:

{
  "conversation_summary": "Caller booked a ride from 123 Main St to the airport for 6pm."
}

Examples

Minimal AI agent

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

Saved AI agent

version: 1.0.0
sections:
  main:
    - answer: {}
    - ai:
        agent: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Hints

ai:
  hints:
  - Tony
  - hint: swimmel
    pattern: swimmel
    replace: SWML

Pronounce

version: 1.0.0
sections:
  main:
    - ai:
        prompt:
          text: |
            You are an expert in the GIF file format. Tell the user whatever they'd like to know in this
            field.
        pronounce:
          - replace: GIF
            with: jif