---
title: "Create an AI Agent (v2)"
method: POST
path: "/v2/agents"
tags: ["Agents"]
---

# Create an AI Agent (v2)

`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

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).

## Request body

- object
  - `displayName` string: Name shown in chats (also the bot user's first/last name).
  - `avatarUrl` string
  - `bio` string
  - `prompt` string: System prompt (the agent's instructions).
  - `llmProvider` string: Empty means the platform default.
  - `llmModel` string: Empty means the platform default.
  - `embeddingModel` string
  - `contextSize` integer
  - `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`.
  - `responseProbability` number
  - `cooldownSec` integer: Minimum seconds between two replies in one room.
  - `greetingMessage` string
  - `isRAG` boolean: Answer with the agent's knowledge (Web Index and Docs Index).
  - `ragTags` string[]: Restrict retrieval to sources carrying these tags.
  - `categories` string[]: Directory categories. Values outside the list are a 422; spelling is normalised and duplicates dropped.
  - `soulMd` string: The agent's long-lived notes, shown as "Memory" in the admin UI. Later edits go through `POST /v2/agents/{idOrAddress}/soul`.
  - `heartbeat` object
    - `enabled` boolean
    - `schedule` string
    - `prompt` string
  - `flowsYaml` string: 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'
  - `ownerAppId` string: Home App of the agent. Must be an App the caller manages, otherwise 403 `OWNER_APP_FORBIDDEN`.

## Response `201`

```
{ ok: true, agent: Agent }
```

## Other responses

- `400`: The flows script does not compile. ``` { error: 'Invalid flows script', code: 'FLOWS_INVALID', details: [{ path, message, line? }] } ```
- `401`: Unauthorized
- `403`: `OWNER_APP_FORBIDDEN` (ownerAppId is not an App the caller manages), `AGENTS_DISABLED` (agent creation is turned off for this account), or `LICENSE_FEATURE_NOT_INCLUDED` (the edition has no `ai` feature).
- `404`: Not Found
- `422`: Validation error, including an unknown category. ``` { error: string, code: 'VALIDATION_ERROR' } ```
- `500`: Internal Server Error

---

[API](https://skmtc.dev/ethora/apis/platform-api.md) · [All operations](https://skmtc.dev/ethora/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ethora/apis/platform-api/revisions/01b6e64378ee?raw)