Create Agent
ethora-agents-create-v2Create a configurable AI agent persona for Ethora chat, defining its name, avatar, system prompt, and reply behavior (response mode, cooldown) for use in single or multi-agent rooms.
Instructions
Create a reusable AI agent (POST /v2/apps/:appId/agents). Works in user auth mode (the normal hosted mode) or B2B mode; app-token mode is not accepted by the backend. Each agent is a persona — name, avatar, system prompt, LLM config, plus response-gate settings (responseMode, cooldownSec) that control when it speaks in a room. For multi-agent scenarios (two or more personas conversing in one chat) create each one separately, then ethora-agent-invite-to-chat them into the same room. See the ethora-agents-quickstart prompt for the end-to-end recipe.
Requires: a selected app (ethora-app-select) or an explicit appId; the agent is owned by that app.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Short display name. For multi-agent scenarios, prefer single-word names (e.g. 'Hannibal', 'Varro') — the @-mention matcher uses the exact display name with word-boundary matching. | |
| slug | No | URL-safe slug (auto-generated from name if omitted). | |
| appId | No | 24-char hex appId the agent belongs to (`POST /v2/apps/:appId/agents`). Defaults to the app selected with `ethora-app-select`. Pass it when you just created an app so the agent lands there rather than in the token's own app. | |
| isRAG | No | Enable retrieval-augmented generation from indexed sources. | |
| prompt | No | System prompt — the agent's persona, role, style of speech, and behaviour rules. For multi-agent scenarios, instruct the agent to end every message with an @-mention of who speaks next; that's how turn-handoff works through the response gate. | |
| ragTags | No | Optional RAG tag filter — restrict retrieval to sources matching these tags. | |
| summary | No | Short bio shown in agent lists. | |
| trigger | No | Legacy trigger field. Prefer the newer `responseMode` for new agents. | |
| llmModel | No | LLM model override (e.g. 'gpt-4o-mini'). | |
| 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 | Free-form category tags for agent directory listings. | |
| visibility | No | 'private' (only invitable inside the owning app) 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 in multi-agent scenarios. | |
| isPublished | No | Convenience alias for setting visibility='public'. | |
| llmProvider | No | LLM provider override (e.g. 'openai'). Defaults to the app's configured provider. | |
| botAvatarUrl | No | URL of the avatar image shown next to bot messages. | |
| responseMode | No | When the agent decides to reply. 'always' = every room message; 'mentioned' = only when @-mentioned by display name or via /bot (recommended for multi-agent turn-taking); 'smart' = a mini LLM gate decides per-message; 'probability' = coin-flip per message using `responseProbability`. | |
| botDisplayName | No | Display name used inside the chat UI. Defaults to `name`. | |
| greetingMessage | No | Optional message the agent posts when it first joins a room. | |
| responseProbability | No | If responseMode='probability', odds (0-1) of replying to each message. Damped 0.6x for bot-to-bot messages. |