--- title: "Create AI agent" method: POST path: "/api/fabric/resources/ai_agents" tags: ["AI Agents: Custom"] --- # Create AI agent `POST /api/fabric/resources/ai_agents` Creates a custom AI Agent in your SignalWire project. The new agent becomes a reusable Fabric resource for conversational calls and can be reached through resource addresses or assigned as a call handler. Use a [Dialogflow Agent](/docs/apis/rest/ai-agents/ai-agents-dialogflow/list-dialogflow-agents) for an existing Dialogflow integration, or [Create call flow](/docs/apis/rest/call-flows/create-call-flow) for visual, deterministic call logic. #### Permissions The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Voice_, _Messaging_, _Fax_, or _Video_. [Learn more about API scopes](/docs/platform/your-signalwire-api-space). ## Request body - AIAgentCreateRequest - `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 [`ai.hints` in the SWML reference](/docs/swml/reference/calling/ai#aihints). - `languages` object[] — An array of JSON objects defining supported languages in the conversation. Mutually exclusive with `multilingual`: if both are set, `multilingual` is used and this array is ignored. See [`ai.languages` in the SWML reference](/docs/swml/reference/calling/ai#ailanguages). - `params` object — A JSON object containing parameters as key-value pairs. See [`ai.params` in the SWML reference](/docs/swml/reference/calling/ai#aiparams). - `post_prompt` object — The final set of instructions and configuration settings to send to the agent. See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai#aipost_prompt). - `pronounce` object[] — An array of JSON objects to clarify the AI's pronunciation of words or expressions. See [`ai.pronounce` in the SWML reference](/docs/swml/reference/calling/ai#aipronounce). - `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 using markdown formatting. See [`ai.prompt` in the SWML reference](/docs/swml/reference/calling/ai#aiprompt). - `SWAIG` object — An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue. See [`ai.SWAIG` in the SWML reference](/docs/swml/reference/calling/ai#aiswaig). - `name` string, required — Name of the AI Agent. ## Response `201` The request has succeeded and a new resource has been created as a result. - AIAgentResponse - `id` string, uuid, required — Universal Unique Identifier. - `project_id` string, uuid, required — Universal Unique Identifier. - `display_name` string, required — Display name of the AIAgent Fabric Resource - `type` 'ai_agent', required — Type of the Fabric Resource - `created_at` string, date-time, required — Date and time when the resource was created. - `updated_at` string, date-time, required — Date and time when the resource was updated. - `ai_agent` AIAgent, required — 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 through SignalWire AI Gateway (SWAIG). See the [SWML `ai` method reference](/docs/swml/reference/calling/ai) for the complete configuration contract. - `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 [`ai.hints` in the SWML reference](/docs/swml/reference/calling/ai#aihints). - `languages` object[] — An array of JSON objects defining supported languages in the conversation. Mutually exclusive with `multilingual`: if both are set, `multilingual` is used and this array is ignored. See [`ai.languages` in the SWML reference](/docs/swml/reference/calling/ai#ailanguages). - `params` object — A JSON object containing parameters as key-value pairs. See [`ai.params` in the SWML reference](/docs/swml/reference/calling/ai#aiparams). - `post_prompt` object — The final set of instructions and configuration settings to send to the agent. See [`ai.post_prompt` in the SWML reference](/docs/swml/reference/calling/ai#aipost_prompt). - `pronounce` object[] — An array of JSON objects to clarify the AI's pronunciation of words or expressions. See [`ai.pronounce` in the SWML reference](/docs/swml/reference/calling/ai#aipronounce). - `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 using markdown formatting. See [`ai.prompt` in the SWML reference](/docs/swml/reference/calling/ai#aiprompt). - `SWAIG` object — An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue. See [`ai.SWAIG` in the SWML reference](/docs/swml/reference/calling/ai#aiswaig). - `agent_id` string, uuid, required — Universal Unique Identifier. - `name` string, required — Name of the AI Agent. ## Other responses - `401` — Access is unauthorized. - `404` — The server cannot find the requested resource. - `422` — The request contains invalid parameters. See errors for details. - `500` — An internal server error occurred. ## Changes > 161 revisions in range; 3 could not be searched. - **2026-08-20** `173ff877e9cd` — 1 breaking, 7 warning, 1 info - request property `hints/items/` list-of-types was narrowed by removing types `object` from media type `application/json` - removed the request property `agent_id` - removed the request property `global_data` - removed the request property `multilingual` - …5 more - **2026-08-20** `e79dcc8b2150` — 24 breaking, 35 warning, 15 info - removed `#/components/schemas/SWML.Calling.Hint` from the `hints/items/` request property `anyOf` list - the `SWAIG` request property type changed from no type to `object` - the `global_data` request property type changed from no type to `object` - the `multilingual` request property type changed from no type to `object` - …70 more - **2026-08-18** `51e63ae4cf55` — 1191 breaking, 2 warning - added the new required request property `languages/items/code` - added the new required request property `languages/items/name` - added the new required request property `languages/items/voice` - added `#/components/schemas/SWML.Calling.FunctionFillers` to the `prompt/allOf[#/components/schemas/SWML.Calling.AIPrompt]/anyOf[subschema #1: Prompt with Text]/contexts/allOf[subschema #1: contexts]/default/allOf[#/components/schemas/SWML.Calling.ContextsObject]/anyOf[#/components/schemas/SWML.Calling.ContextsTextObject]/enter_fillers` request property `allOf` list - …1189 more - …this revision’s changelog is incomplete - …earlier changes not shown [Full history](https://skmtc.dev/signalwire/apis/signalwire-rest-api/changes/api/fabric/resources/ai_agents/post.md) --- [API](https://skmtc.dev/signalwire/apis/signalwire-rest-api.md) · [All operations](https://skmtc.dev/signalwire/apis/signalwire-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signalwire/apis/signalwire-rest-api/revisions/20ee0f568ece?raw)