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

# Create agent with AI brief

`POST /agent/with-ai`

Create a new single-prompt agent from a natural-language brief or structured
question/answer pairs. Atoms generates the system prompt for you.

Provide either `description` (free-form brief) or a non-empty `questions` array,
but not both. The `emotiveToggle`, `voiceId`, and `voiceModel` fields must be
supplied as a 3-tuple or omitted entirely.

## Request body

- object
  - `name` string — Agent name (trimmed). Auto-generated when omitted.
  - `description` string — Free-form natural-language description of what the agent should do. Atoms turns this into the system prompt. Use this OR `questions`, not both.
  - `questions` object[] — Structured question/answer pairs. Atoms uses these to compose the system prompt. Use this OR `description`, not both.
    - `question` string, required
    - `answer` string, required
  - `type` 'single_prompt' — Currently the only supported agent type.
  - `emotiveToggle` boolean — Enable emotive synthesis. Must be paired with `voiceId` + `voiceModel`.
  - `voiceId` string — Voice ID for synthesis. Must be paired with `emotiveToggle` + `voiceModel`.
  - `voiceModel` 'waves' | 'waves_lightning_large' | 'waves_lightning_large_voice_clone' | 'waves_lightning_v2' | 'waves_lightning_v3' | 'waves_lightning_v3_1' | 'gpt-realtime' | 'gpt-realtime-mini' | 'other' — Synthesizer to use. Must be paired with `emotiveToggle` + `voiceId`.
  - `knowledgeBaseId` string — Optional knowledge-base ID to attach to the new agent.

## Response `201`

Agent created. `data` is the new agent's `_id` (string).

- object
  - `status` boolean
  - `data` string — Newly created agent ID.

## Other responses

- `400` — Bad request — validation failed or required field missing.
- `401` — Unauthorized access
- `500` — Internal server error

## Changes

- **2026-06-21** `ea4ea58d7c4e` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/smallest-inc/apis/agent-management-api/changes/agent/with-ai/post.md)

---

[API](https://skmtc.dev/smallest-inc/apis/agent-management-api.md) · [All operations](https://skmtc.dev/smallest-inc/apis/agent-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/smallest-inc/agent-management-api/revisions/ea4ea58d7c4e/schema)