> For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt # ai > Create an AI agent to interact with users. [languages]: /docs/swml/reference/calling/ai/languages [multilingual]: /docs/swml/reference/calling/ai/multilingual [params]: /docs/swml/reference/calling/ai/params [prompt]: /docs/swml/reference/calling/ai/prompt [SWAIG]: /docs/swml/reference/calling/ai/swaig [set_global_data action]: /docs/swml/reference/calling/ai/swaig/functions/data-map#list-of-valid-actions [prompt-engineering]: /docs/platform/ai/prompt-engineering [markdown-guide]: https://www.markdownguide.org/ 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)][SWAIG]. Since the [prompt] configuration is central to AI agent behavior, it is recommended to read the [prompt engineering][prompt-engineering] guide. ## **Properties** **`ai`** `object` — required 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` — required 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][prompt] using [markdown formatting][markdown-guide] as LLMs better understand structured content. It is also recommended to read the [prompt engineering][prompt-engineering] 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`][set_global_data action] 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[]` Provide an array of strings and/or objects to guide the AI's pronunciation and understanding of specific words or phrases. Words that can commonly be mispronounced can be added to the hints to help the AI speak more accurately. **Hints as strings:** Each string in the array gives the AI context on how to interpret certain words. For example, if a user says `Toni` and the hint is `Tony`, the AI understands that the user said `Tony`. **Hints as objects:** An array of objects with the properties below to customize how the AI handles specific words. --- **`hints[].hint`** `string` — required The hint to match. This will match the string exactly as provided. --- **`hints[].pattern`** `string` — required A regular expression to match the hint against. This will ensure that the hint has a valid matching pattern before being replaced. --- **`hints[].replace`** `string` — required The text to replace the hint with. This will replace the portion of the hint that matches the pattern. --- **`hints[].ignore_case`** `boolean` — default: false If true, the hint will be matched in a case-insensitive manner. Defaults to false. --- **`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. --- **`post_prompt.text`** `string` — required The instructions to send to the agent. --- **`post_prompt.temperature`** `number` — default: 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`** `number` — default: 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`** `number` — default: 0.6 Threshold 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. --- **`post_prompt.presence_penalty`** `number` — default: 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`** `number` — default: 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](#post_prompt_url-callback) below. --- **`ai.pronounce`** `object[]` An array of objects to clarify the AI's pronunciation of certain words or expressions. --- **`pronounce[].replace`** `string` — required The expression to replace. --- **`pronounce[].with`** `string` — required The phonetic spelling of the expression. --- **`pronounce[].ignore_case`** `boolean` — default: true Whether the pronunciation replacement should ignore case. --- **`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. --- ## post\_prompt\_url callback SignalWire sends the report to your `post_prompt_url` as an HTTP `POST`. See the [AI post-prompt callback](/docs/apis/rest/webhooks/ai-post-prompt-callback) webhook page for the full field reference. ### 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`](/docs/swml/reference/calling/ai/params#paramsconversation_id) and [`save_conversation`](/docs/swml/reference/calling/ai/params#paramssave_conversation) enabled. Return the summary you stored for that `conversation_id` under a `conversation_summary` key, and the agent resumes with it: ```json { "conversation_summary": "Caller booked a ride from 123 Main St to the airport for 6pm." } ``` ## Examples ### Minimal AI agent #### YAML ```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 ```json { "version": "1.0.0", "sections": { "main": [ { "answer": {} }, { "ai": { "prompt": { "text": "You are a customer service agent. Answer questions about account status and billing." } } } ] } } ``` ### Hints #### YAML ```yaml ai: hints: - Tony - hint: swimmel pattern: swimmel replace: SWML ``` #### JSON ```json { "ai": { "hints": [ "Tony", { "hint": "swimmel", "pattern": "swimmel", "replace": "SWML" } ] } } ``` ### Pronounce #### YAML ```yaml 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 ``` #### JSON ```json { "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\nfield.\n" }, "pronounce": [ { "replace": "GIF", "with": "jif" } ] } } ] } } ```