prompt | SignalWire

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. It is also recommended to read the prompt engineering guide.

Prompt types

There are three ways to define prompt content, each suited for different use cases:

Text prompt — A single string containing the full prompt. Best for simple agents where the entire personality, instructions, and rules fit naturally into one block of text.
POM (Prompt Object Model) — A structured array of sections with titles, body text, and bullet points. Best for complex prompts that benefit from clear organization. SignalWire renders the POM into a markdown document before sending it to the LLM.
Contexts — A system of named conversation flows, each with its own steps, memory settings, and transition logic. Best for multi-stage conversations where the agent needs to switch between distinct modes (e.g., greeting → support → billing). Requires a default context as the entry point. See Contexts below.

Text and POM are mutually exclusive — use one or the other. Contexts can be combined with either a text or POM prompt to add structured conversation flows on top of the base prompt.

Properties

ai.prompt

object

An object that contains the prompt parameters.

The prompt property accepts one of the following objects:

Regular Prompt

POM Prompts

prompt.text

stringRequired

The main identity prompt for the AI. This prompt will be used to outline the agent’s personality, role, and other characteristics.

prompt.model

string

The AI model for the conversation. Takes precedence over params.ai_model. 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.

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.

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.

prompt.confidence

numberDeprecated

Has no effect and can be omitted.

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.

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.

prompt.max_tokens

integerDefaults to 256

Limits the amount of tokens that the AI agent may generate when creating its response. Valid value range: 0 - 4096.

prompt.contexts

object

An object that defines the available contexts for the AI. Each context represents a set of steps that guide the flow of the conversation. The object must include a default key, which specifies the initial context used at the start of the conversation. Additional contexts can be added as other keys within the object.

contexts.default

objectRequired

The default context used at the beginning of the conversation.

contexts.*

object

Additional contexts for specialized conversation flows. The key is user-defined (e.g., support, sales, billing).

*.steps

object[]Required

An array of step objects that define the conversation flow for this context. Steps execute sequentially unless otherwise specified. See steps for the properties of each step.

*.prompt

string

Instructions for this context. They are added to the instructions of each step in the context.

*.pom

object[]

Instructions for this context as a POM. Set either prompt or pom, not both. Sections take the same properties as prompt.pom.

*.initial_step

string

The name of the step to start at when this context is entered, matched case-insensitively. When omitted, or when no step has that name, the context starts at its first step.

*.history

stringDefaults to default

How much of the earlier conversation the AI sees when it moves from one step to the next in this context:

default hides the instructions of earlier steps but keeps the conversation.
keep keeps the instructions of earlier steps and the conversation.
hide hides the instructions of earlier steps and the earlier conversation, including function calls and their results.

*.valid_steps

string[]

Steps the AI can move to when it switches to this context, before the current step’s own valid_steps apply. Include next to allow the following step.

*.valid_contexts

string[]

Contexts the AI can switch to when it switches to this context, before the current step’s own valid_contexts apply.

*.post_prompt

object

A post-prompt for the end-of-call summary. While this context is active, including when it is the starting context, it replaces ai.post_prompt; switching to a context without one restores ai.post_prompt. Takes the same properties as ai.post_prompt except model.

*.isolated

booleanDefaults to false

When true, resets conversation history to only the system prompt when entering this context. Useful for focused tasks that shouldn’t be influenced by previous conversation.

*.enter_fillers

object

Filler phrases played when entering this context, keyed by language code. One phrase is picked at random, never the same one twice in a row.

enter_fillers.*

string[]

An array of filler phrases for one language code. See filler language codes for the codes in common use and the order the agent checks the keys in. Two keys are not language codes: auto has the phrases translated into whichever language is being spoken, and default covers every language you have not listed.

*.exit_fillers

object

Filler phrases played when leaving this context. Same format as enter_fillers.

prompt.steps

object[]

An array of steps for a conversation that needs only one context. It works like the steps of a default context, with the properties described in steps. Ignored when prompt.contexts is set.

Steps

Each entry in a context’s steps, or in prompt.steps, is a step object. A step gives its instructions in text or pom; a step with gather_info doesn’t need either, and a step with reset doesn’t use them.

steps[].name

stringRequired

The name of the step, unique within its context. It can’t be next, which refers to the following step.

steps[].text

string

The instructions for this step. Required unless the step sets pom, reset, or gather_info. Set either text or pom, not both.

steps[].pom

object[]

The instructions for this step as a POM. Sections take the same properties as prompt.pom.

steps[].step_criteria

string

The criteria that must be met before the AI moves on from this step, given to the AI as an instruction. Custom criteria are highly recommended to get the intended behavior.

steps[].functions

string[]

Names of the SWAIG functions the AI can call during this step. When omitted, the functions that were already available stay available. An empty array makes none of the SWAIG functions available during this step.

steps[].valid_steps

string[]

Names of the steps the AI can move to from this step. Include next to allow the following step. When omitted, the AI can move to the next step in the context. An empty array means that, once the AI’s available functions are refreshed for this step (for example, when the step sets functions), it is no longer offered a move to another step. A change_step action returned by a SWAIG function still works.

steps[].valid_contexts

string[]

Names of the contexts the AI can switch to from this step. Each must be a context defined in prompt.contexts.

steps[].skip_user_turn

booleanDefaults to false

If true, the AI responds to this step’s instructions without waiting for the caller to speak first. It doesn’t move to the next step on its own; set skip_to_next_step as well for that.

steps[].skip_to_next_step

booleanDefaults to false

Used together with skip_user_turn: after the AI’s response, the conversation moves to the next step. Has no effect on its own.

steps[].end

booleanDefaults to false

If true, this is the last step in the context. Can’t be used together with valid_steps.

steps[].reset

object

Resets the conversation with new instructions when this step becomes active, and makes this the last step in the context, like end. When reset is set, the step’s text, pom and gather_info are not used; put the new instructions in reset.system_prompt.

reset.system_prompt

string

The new instructions. Variables such as ${caller_id_number} are expanded, as in prompt.text.

reset.user_prompt

string

A message added as if the caller had said it, right after the reset. When consolidate is not true, defaults to hello. Variables are expanded, as in prompt.text.

reset.consolidate

booleanDefaults to false

If true, the conversation so far is summarized and the summary is carried over after the reset.

reset.full_reset

booleanDefaults to false

If true, system_prompt replaces the agent’s original prompt. Otherwise the conversation is cleared and system_prompt is added as a new instruction.

steps[].gather_info

object

Asks the caller a list of questions and stores the answers in global_data. While questions remain, the AI asks them one at a time and doesn’t move to another step.

gather_info.questions

object[]Required

The questions to ask, in order. At least one is required.

questions[].key

stringRequired

The key the answer is stored under in global_data, or under output_key when it is set.

questions[].question

stringRequired

The question the AI asks the caller.

questions[].type

stringDefaults to string

The type of the answer, as a JSON Schema type such as string, number, integer, or boolean.

questions[].confirm

booleanDefaults to false

If true, the AI reads the answer back and gets the caller’s confirmation before accepting it.

questions[].prompt

string

Extra instructions for this question, added after the question.

questions[].functions

string[]

Names of SWAIG functions the AI can call while asking this question. Other functions are unavailable during the question.

questions[].isolated

boolean

If true, the answers to the other questions in this gather are hidden from the AI while it asks this one, so it must ask rather than work out the answer. Defaults to the isolated value of gather_info.

gather_info.prompt

string

Instructions added before the first question.

gather_info.pom

object[]

Instructions added before the first question, as a POM. Used when prompt is not set.

gather_info.output_key

string

A global_data key to store all the answers under, as an object keyed by each question’s key. When omitted, each answer is stored directly in global_data under its key.

gather_info.completion_action

string

What to do after the last question is answered: next_step moves to the following step, and any other value is the name of the step to move to. When omitted, the conversation stays on the current step.

gather_info.isolated

booleanDefaults to false

If true, the answers to the other questions are hidden from the AI while it asks each question. A question’s own isolated overrides this.

Examples

Basic prompt

version: 1.0.0
sections:
  main:
    - ai:
        prompt:
          text: |
            You are a friendly customer service agent for a telecommunications company.
            Your name is Alex. Always greet the caller warmly and ask how you can help.
            ## Rules
            - Be polite and professional at all times
            - If the caller asks about billing, offer to transfer them to the billing department
            - If you cannot help with a request, apologize and suggest alternatives
          temperature: 0.8
          top_p: 0.9

POM prompt

version: 1.0.0
sections:
  main:
    - ai:
        prompt:
          pom:
            - title: "Agent Personality"
              body: "You are a friendly and engaging assistant. Keep the conversation light and fun."
              subsections:
                - title: "Personal Information"
                  numberedBullets: true
                  bullets:
                    - "You are a AI Agent"
                    - "Your name is Frank"
                    - "You work at SignalWire"
            - title: "Task"
              body: "You are to ask the user a series of questions to gather information."
              bullets:
                - "Ask the user to provide their name"
                - "Ask the user to provide their favorite color"
                - "Ask the user to provide their favorite food"
                - "Ask the user to provide their favorite movie"
                - "Ask the user to provide their favorite TV show"
                - "Ask the user to provide their favorite music"
                - "Ask the user to provide their favorite sport"
                - "Ask the user to provide their favorite animal"

Rendered prompt

The above POM example will render the following markdown prompt:

## Agent Personality
You are a friendly and engaging assistant. Keep the conversation light and fun.
### Personal Information
1. You are a AI Agent
2. Your name is Frank
3. You work at SignalWire
## Task
You are to ask the user a series of questions to gather information.
- Ask the user to provide their name
- Ask the user to provide their favorite color
- Ask the user to provide their favorite food
- Ask the user to provide their favorite movie
- Ask the user to provide their favorite TV show
- Ask the user to provide their favorite music
- Ask the user to provide their favorite sport
- Ask the user to provide their favorite animal

Basic context

version: 1.0.0
sections:
  main:
    - ai:
        prompt:
          text: You are a helpful assistant that can switch between different expertise areas.
          contexts:
            default:
              steps:
                - name: greeting
                  text: Greet the user and ask what they need help with. If they need technical support, transfer them to the support context.
                  valid_contexts:
                    - support
            support:
              isolated: true
              enter_fillers:
                en-US: ["Switching to technical support", "Let me connect you with support"]
                es: ["Cambiando a soporte técnico", "Permítame conectarlo con soporte"]
              exit_fillers:
                en-US: ["Leaving support mode", "Returning to main menu"]
                es: ["Saliendo del modo de soporte", "Volviendo al menú principal"]
              steps:
                - name: troubleshoot
                  text: Help the user troubleshoot their technical issue. When finished, ask if they need anything else or want to return to the main menu.
                  valid_contexts:
                    - default

Advanced multi-context

This example demonstrates multiple contexts with different AI personalities, voice settings, and specialized knowledge domains:

sections:
  main:
    - ai:
        hints:
          - StarWars
          - StarTrek
        languages:
          - name: Ryan-English
            voice: elevenlabs.patrick
            code: en-US
          - name: Luke-English
            voice: elevenlabs.fin
            code: en-US
          - name: Spock-English
            voice: elevenlabs.charlie
            code: en-US
        prompt:
          text: Help the user transfer to the Star Wars or Star Trek expert.
          contexts:
            default:
              steps:
                - name: start
                  text: |+
                    Your name is Ryan. You are a receptionist. Your only purpose is to change the context to starwars or startrek.
                  step_criteria: |+
                    Introduce yourself as Ryan.
                    Ask the user if he would like to talk to a star wars or star trek expert until they provide an adequate answer.
                - name: transfer
                  text: You will now successfully transfer the user to the Star Wars or Star Trek expert.
                  step_criteria: If the user has chosen a valid context, transfer them to the appropriate expert.
                  valid_contexts:
                    - starwars
                    - startrek
            starwars:
              steps:
                - name: start
                  text: |+
                    The user has been transferred to the Star Wars expert.
                    Until told otherwise, your name is Luke. Change the language to Luke-English.
                    Your current goal is to get the user to tell you their name.
                    Unless told otherwise, refer to the user as 'Padawan {users_name}'.
                  step_criteria: |+
                    Introduce yourself as Luke, the Star Wars expert.
                    The user must tell you their name if they only say one word assume that is their name.
                - name: question
                  text: |+
                    Your goal is to get the user to choose one of the following options.
                    - Jedi Order (advance to jedi_order step)
                    - The ways of the Force (advance to force step)
                    - Talk to the star trek expert. (change context to startrek)
                  step_criteria: +|
                    The user must provide a valid answer to continue.
                    Refer to the user as 'Padawan {users_name}' for the rest of the conversation.
                  valid_steps:
                    - jedi_order
                    - force
                  valid_contexts:
                    - startrek
                - name: jedi_order
                  text: |+
                    Limit the topic to the Jedi Order.
                    Inform the user they can say they want to change the topic at any time, if they do move to the question step.
                  step_criteria: The user says they want to change the topic.
                  valid_steps:
                    - question
                - name: force
                  text: |+
                    Limit the topic to the force.
                    Inform the user they can say they want to change the topic at any time, if they do move to the question step.
                  step_criteria: The user says they want to change the topic.
                  valid_steps:
                    - question
            startrek:
              steps:
                - name: start
                  text: |+
                    The user has been transferred to the Star Trek expert.
                    Until told otherwise, your name is Spok. Change the language to Spok-English.
                    Your current goal is to get the user to tell you their name.
                    Unless told otherwise, refer to the user as 'Ensign {users_name}'.
                  step_criteria: |+
                    Introduce yourself as Spok, the Star Trek expert.
                    The user must tell you their name if they only say one word assume that is their name.
                - name: question
                  text: |+
                    Your goal is to get the user to choose one of the following options.
                    - Vulcan Culture (advance to vulcan_culture step)
                    - Federation (advance to federation step)
                    - Talk to the star wars expert. (change context to starwars)
                  step_criteria: +|
                    The user must provide a valid answer to continue.
                    Refer to the user as 'Ensign {users_name}' for the rest of the conversation.
                  valid_steps:
                    - vulcan_culture
                    - federation
                  valid_contexts:
                    - starwars
                - name: vulcan_culture
                  text: |+
                    Limit the topic to Vulcan Culture.
                    Inform the user they can say they want to change the topic at any time, if they do move to the question step.
                  step_criteria: The user says they want to change the topic.
                  valid_steps:
                    - question
                - name: federation
                  text: |+
                    Limit the topic to the Federation of Planets.
                    Inform the user they can say they want to change the topic at any time, if they do move to the question step.
                  step_criteria: The user says they want to change the topic.
                  valid_steps:
                    - question

Variable Expansion

Use the following syntax to expand variables into your prompt.

${call_direction}

string

Inbound or outbound.

${caller_id_number}

string

The caller ID number.

${local_date}

string

The local date.

${spoken_date}

string

The spoken date.

${local_time}

string

The local time.

${time_of_day}

string

The time of day.

${supported_languages}

string

A list of supported languages.

${default_language}

string

The default language.