Agents

Create an AI Agent (v2)

Creates an Agent owned by the caller, with a fresh EOA-style address. Supports User JWT and B2B Server JWT (the owner is then the token's tenant App).

An Agent is account-level: it is embodied in an App as a BotInstance the first time it is invited into one of that App's chats (POST /v2/agents/{idOrAddress}/invite-to-chat).

Defaults for omitted fields: displayName "AI Agent", prompt "You are a helpful assistant.", responseMode smart, responseProbability 1, cooldownSec 0, isRAG true, visibility private, ownerAppId the caller's App.

Older field names are still accepted and mapped: name and botDisplayName to displayName, summary to bio, botAvatarUrl to avatarUrl, isPublished: true to visibility: public. slug and meta are accepted and ignored. Any other unknown field is a 422.

Requires the ai license feature and the account's agents capability (a platform admin can turn agent creation off per account).

post/v2/agents

Request

  • Base URL: https://api.chat.ethora.com
  • URL: https://api.chat.ethora.com/v2/agents
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer

Request body

displayNamestring

Name shown in chats (also the bot user's first/last name).

avatarUrlstring
biostring
promptstring

System prompt (the agent's instructions).

llmProviderstring

Empty means the platform default.

llmModelstring

Empty means the platform default.

embeddingModelstring
contextSizeinteger
responseMode'always' | 'mentioned' | 'smart' | 'probability'

When the agent replies in a room. always answers every human message, mentioned only when addressed, smart decides per message, probability replies with responseProbability.

responseProbabilitynumber
cooldownSecinteger

Minimum seconds between two replies in one room.

greetingMessagestring
isRAGboolean

Answer with the agent's knowledge (Web Index and Docs Index).

ragTagsstring[]

Restrict retrieval to sources carrying these tags.

categoriesstring[]

Directory categories. Values outside the list are a 422; spelling is normalised and duplicates dropped.

soulMdstring

The agent's long-lived notes, shown as "Memory" in the admin UI. Later edits go through POST /v2/agents/{idOrAddress}/soul.

flowsYamlstring

Flows script (scripted conversations) in YAML. Compiled on save; a script that does not compile is a 400 and nothing is saved. Check one first with POST /v2/agents/flows/validate.

visibility'private' | 'unlisted' | 'public'
ownerAppIdstring

Home App of the agent. Must be an App the caller manages, otherwise 403 OWNER_APP_FORBIDDEN.

Response 

{ ok: true, agent: Agent }

Changes

No recorded changes to this operation across all 1 revision of this API.