Update Agent
ethora-agent-updateDestructiveIdempotent
Overwrites the fields you pass; previous values are not kept and cannot be restored from the API, so confirm changes to the prompt, name or settings with the user first. Update a saved AI agent (PUT /v2/agents/:agentId). All fields are optional - only what you pass is updated. Common uses: tune the system prompt after a test run, switch responseMode to control turn-taking in multi-agent rooms, or adjust cooldownSec. See ethora-agents-quickstart prompt for the end-to-end recipe.
Requires: an agent id or address from ethora-agent-list or ethora-agent-create. Only the agent's owner can update it: a public agent from someone else, including the platform's Support Agent, answers 403, so ethora-agent-clone it and update the copy.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New display name. For multi-agent scenarios prefer single-word names — the @-mention matcher uses exact display-name match with word-boundary. | |
| slug | No | URL-safe slug. | |
| isRAG | No | Enable RAG retrieval. | |
| prompt | No | Updated system prompt (persona + behaviour). For multi-agent rooms instruct the agent to end every message with an @-mention of the next speaker — that's how turn-handoff works through the response gate. | |
| agentId | No | Mongo _id (24 hex chars) of the agent to update. | |
| ragTags | No | Restrict the bot's knowledge to sources carrying at least one of these tags; `[]` removes the restriction. | |
| summary | No | Short bio. | |
| trigger | No | Legacy trigger field. Prefer `responseMode`. | |
| llmModel | No | LLM model override. | |
| flowsYaml | No | Deterministic scripted conversation for this agent, as YAML. Drives the agent through a fixed sequence (opening menu, appointment request, intake questionnaire, survey) instead of leaving every turn to the model. Compiled and validated server-side on save: an invalid script is rejected with code `FLOWS_INVALID` and per-line details, and nothing is stored. A flow named `start` is reserved and fires when a conversation opens. Buttons are authored here (`buttons:` on a `say` step, or `options:` on an `ask` step). Call `fetch` with id `doc:agent-flows` for the full authoring format before writing one. Pass an empty string to clear the script. | |
| categories | No | Directory categories, any of: `customer-support` (customer-facing assistants), `persona` (a character or historical figure), `entertainment` (quizzes, games, scenarios), `worker` (internal work). Used to filter `ethora-agent-list`. Replaces the agent's current set. | |
| visibility | No | 'private' or 'public' (cross-app invitable). | |
| cooldownSec | No | Minimum seconds between this agent's replies in a given room. Damped 2x for bot-to-bot. Set 0 for quick turn-taking. | |
| isPublished | No | Convenience alias for visibility='public'. | |
| llmProvider | No | LLM provider override. | |
| botAvatarUrl | No | Avatar image URL. | |
| responseMode | No | When the agent replies. 'always' = every message; 'mentioned' = only @-mention or /bot (best for multi-agent turn-taking); 'smart' = mini-LLM decides; 'probability' = coin-flip using `responseProbability`. | |
| botDisplayName | No | Display name in chat UI. | |
| greetingMessage | No | Message the agent posts when it first joins a new room. | |
| agentIdOrAddress | No | Alias for `agentId` - either name is accepted, pass whichever you have. | |
| responseProbability | No | If responseMode='probability', odds (0-1) of replying. Damped 0.6x for bot-to-bot. |