---
title: "Create Agent"
method: POST
path: "/api/v1/agents"
tags: ["Agents"]
---

# Create Agent

`POST /api/v1/agents`

## Request

- Base URL: `https://api.dialogbrain.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.dialogbrain.com/api/v1/agents`
- Auth: none declared

Create an agent in the key's workspace and return the full record, prompts included.

Requires Idempotency-Key: a retried request with the same key returns the agent created the first time instead of a second one.

## Headers

- `Idempotency-Key` string, nullable

## Request body

- AgentCreateRequest
  - `name` string, required: Name of the AI agent (1-100 characters)
  - `description` string, nullable: Optional description of what this agent does
  - `text_engine` 'rule_based' | 'agentic' | 'claude_channels' | 'external_agent', nullable: Text-execution engine: 'rule_based', 'ai_assisted', 'agentic' (default), 'claude_channels', or 'external_agent' (the run is handed to an agent outside DialogBrain; needs remote_tool). Voice is derived from triggers, not engine. OMIT to use the default ('agentic').
  - `remote_tool` string, nullable: For an external_agent: the integration tool that starts the remote agent.
  - `send_mode` 'auto' | 'draft', nullable: Default send mode: 'auto' or 'draft'. OMIT to use 'draft' (the default).
  - `prompt_id` integer, nullable: ID of the prompt to assign to this agent
  - `template` 'dm-auto-reply', nullable: Optional template slug to instantiate the agent + its built-in trigger from (deterministic). Use 'dm-auto-reply' for the customer DM auto-reply agent (incoming DM trigger, draft mode). When set, the trigger comes from the template — you don't need agents.trigger_create. OMIT to create a plain agent (no template).
  - `prompt_text` string, nullable: The agent's persona and instructions.
  - `model` 'claude-haiku-4-5-20251001' | 'claude-opus-4-6' | 'claude-sonnet-4-6' | 'claude-sonnet-5' | 'dashscope-glm-5.2' | 'dashscope-glm-5.2-nothink' | 'deepseek-v4-flash' | 'deepseek-v4-flash-nothink' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-4o' | 'kimi-k2.6' | 'qwen-flash' | 'qwen-plus' | 'qwen3-vl-plus' | 'qwen3.6-flash' | 'qwen3.6-plus', nullable: The model the agent runs on; omit for the platform default.
  - `allowed_tools` unknown[], nullable: Names of the capabilities this agent may use. Omit for the standard set (knowledge base, replying, lead capture, reading files, handoff); a list you pass replaces it.
    - unknown
  - `max_iterations` integer, nullable: Hard cap on agentic-loop turns per run (1-50). OMIT for the default (10).

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway.md) · [All operations](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway/revisions/77bef09a9209?raw)