---
title: "Create agent with AI"
method: POST
path: "/agent/with-ai"
tags: ["Agents"]
---

# Create agent with AI

`POST /agent/with-ai`

Creates a new agent using AI generation. Accepts either a guided questionnaire (array of Q&A pairs) or a free-text description. The AI generates the agent's prompt and configuration. A security check is run on the generated prompt before the agent is persisted. Deducts credits on success.

**Rules:**
- Either `questions` (non-empty array) or `description` must be provided — not both.
- `emotiveToggle`, `voiceId`, and `voiceModel` must either all be present or all be absent.
- When `emotiveToggle=true`, `voiceModel` must be `GPT_REALTIME`.
- When `emotiveToggle=false`, `voiceModel` cannot be `GPT_REALTIME`.

## Request body

- object
  - `name` string — Agent name. Auto-generated if omitted.
  - `description` string — Free-text description. Required if `questions` not given.
  - `questions` object[] — Guided Q&A pairs. Required if `description` not given.
    - `question` string, required
    - `answer` string, required
  - `type` 'single_prompt' — Workflow type. Only `single_prompt` is supported.
  - `emotiveToggle` boolean — Enable emotive (GPT Realtime) mode. Must be given with `voiceId` and `voiceModel`.
  - `voiceId` string — Voice ID. Must be given together with `emotiveToggle` and `voiceModel`.
  - `voiceModel` string — Voice model. Must be given together with `emotiveToggle` and `voiceId`.
  - `knowledgeBaseId` string — Knowledge base to attach (must belong to the organization).

## Response `201`

Agent created — returns the new agent's ObjectId

- object
  - `success` boolean
  - `data` string — MongoDB ObjectId of the created agent

## Other responses

- `400` — Invalid request body, or the generated prompt failed the security check
- `401` — Unauthorized access
- `403` — Organization lacks access to the requested workflow type or model (WORKFLOW_GRAPH, GPT 5.2, Electron Kogta)
- `500` — Internal server error
- `503` — Security check service temporarily unavailable

---

[API](https://skmtc.net/smallest-inc/apis/agent-management-api.md) · [All operations](https://skmtc.net/smallest-inc/apis/agent-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smallest-inc/agent-management-api/versions/6d1036a76fbc/schema)