Create Agent
ethora-agent-createCreate 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 them into the same room. See the ethora-agents-quickstart prompt for the end-to-end recipe. To start from a ready-made public agent instead, ethora-agent-list { visibility: "public" } then ethora-agent-clone.
Requires: a selected app (ethora-app-select) or an explicit appId. The agent belongs to your account (only you can change it) and is homed in that app; it can still be used in your other apps.
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 | Restrict this agent's knowledge to sources carrying at least one of these tags; `[]` removes the restriction. If no source carries any of the tags the agent answers without knowledge, so tag the sources first. | |
| summary | No | Short bio shown in agent lists. | |
| trigger | No | Legacy trigger field. Prefer the newer `responseMode` for new agents. | |
| llmModel | No | Model id served by this deployment's AI endpoint; omit for the platform default. `ethora-agent-model-list` returns the supported ids; an unsupported id is rejected with LLM_MODEL_UNSUPPORTED and that list. | |
| 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' (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 | Leave empty. The deployment has one AI endpoint (OpenAI-compatible); `openai` and `openai-compatible` are accepted as synonyms, anything else is rejected with LLM_PROVIDER_UNSUPPORTED. | |
| 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. |