--- title: "Update AI agent" method: PATCH path: "/api/fabric/resources/ai_agents/{id}" tags: ["AI Agents: Custom"] --- # Update AI agent `PATCH /api/fabric/resources/ai_agents/{id}` Updates how an existing custom AI Agent behaves in conversations. Use it for an agent configured directly in your SignalWire project; update a linked Dialogflow resource with [Update Dialogflow agent](/docs/apis/rest/ai-agents/ai-agents-dialogflow/update-dialogflow-agent). #### 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). ## Path parameters - `id` string, uuid, required — Universal Unique Identifier. ## Request body - AIAgentUpdateRequest - `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 — 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 — Name of the AI Agent. ## Response `200` The request has succeeded. - 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 > 137 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/format changed from ``/`` to `object`/`` - the `global_data` request property type/format changed from ``/`` to `object`/`` - the `multilingual` request property type/format changed from ``/`` to `object`/`` - …70 more - …earlier changes not shown [Full history](https://skmtc.dev/signalwire/apis/signalwire-rest-api/changes/api/fabric/resources/ai_agents/:id/patch.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-service-production.skmtc.workers.dev/v1/apis/signalwire/signalwire-rest-api/revisions/792d5b8e2970/schema)