# Agents: Create an agent (https://docs.envocal.ai/api-reference/agents/create-an-agent/)

> Creates the agent in the tenant together with a default widget configuration whose settings are all unset (the widget's defaults apply; change them with PUT /v1/tenants/{tenantId}/agents/{agentId}/widget-configs/{id}). Omitted voice settings get defaults (server_vad turn detection, gpt-4o-transcribe transcription, far_field noise reduction). Assign tools with PUT /v1/tenants/{tenantId}/agents/{id}/tools and a phone number with POST /v1/tenants/{tenantId}/agents/{agentId}/phone-numbers/{phoneNumberId}.

## POST `/v1/tenants/{tenantId}/agents`

Creates the agent in the tenant together with a default widget configuration whose settings are all
unset (the widget's defaults apply; change them with `PUT /v1/tenants/{tenantId}/agents/{agentId}/widget-configs/{id}`). Omitted voice settings get
defaults (`server_vad` turn detection, `gpt-4o-transcribe` transcription, `far_field` noise reduction).
Assign tools with `PUT /v1/tenants/{tenantId}/agents/{id}/tools` and a phone number with
`POST /v1/tenants/{tenantId}/agents/{agentId}/phone-numbers/{phoneNumberId}`.

**Required permission:** `agents:write`

### Parameters

| Name | In | | Type | Description |
| --- | --- | --- | --- | --- |
| `tenantId` | path | required | string | Tenant id, or `current` for the key's own tenant. Must be the key's tenant or one of its sub-tenants. |

### Request body

`application/json`: AgentCreateDto

| Field | Type | | Description |
| --- | --- | --- | --- |
| `name` | string | required | Display name. |
| `description` | string | nullable | Internal description; not given to the AI. |
| `instructions` | string | nullable | System prompt. May reference prompt variables as `{{name}}` and system variables such as `{{system_caller_number}}`. |
| `variableDefinitionsJson` | string | nullable | Prompt variables as a JSON-encoded string: an array of `{"name", "jsonType", "placeholder", "description", "required"}`. |
| `status` | `draft` \| `active` \| `archived` | nullable | Lifecycle status. Default `draft`. |
| `model` | string | nullable | Realtime model, e.g. `gpt-realtime`. Omit for the platform default. |
| `voice` | `alloy` \| `ash` \| `ballad` \| `coral` \| `echo` \| `sage` \| `shimmer` \| `verse` \| `marin` \| `cedar` | nullable | Voice for speech output. |
| `knowledgeBaseIds` | string[] | nullable | Knowledge bases to link; they must belong to `tenantId`. |
| `allowFollowUpEmail` | boolean | nullable | Give the AI a `send_email` tool for follow-up emails. Default false. |
| `followUpEmailAddress` | string | nullable | Follow-up email recipient; required when `allowFollowUpEmail` is true. |
| `allowCallTransfer` | boolean | nullable | Give the AI a `transfer_call` tool on phone calls. Default true. |
| `callTransferType` | CallTransferType | nullable | How calls are transferred. Default `direct`. |
| `isTemplate` | boolean | nullable | Make this agent a template for this tenant and its sub-tenants. Default false. |
| `type` | string | nullable | Optional free-text label; not used by the platform. |
| `allowEndCall` | boolean | nullable | Give the AI an `end_call` tool. Default false. |
| `turnDetectionType` | `server_vad` \| `semantic_vad` \| `none` | nullable | `server_vad` (default), `semantic_vad` or `none`. |
| `turnDetectionEagerness` | `auto` \| `low` \| `medium` \| `high` | nullable | `semantic_vad` only. Default `auto`. |
| `turnDetectionThreshold` | number (double) | nullable | `server_vad` only, 0.0–1.0. Default 0.5. |
| `turnDetectionPrefixPadding` | integer | nullable | `server_vad` only, milliseconds. Default 300. |
| `turnDetectionSilenceDuration` | integer | nullable | `server_vad` only, milliseconds. Default 500. |
| `turnDetectionTimeout` | boolean | nullable | `server_vad` only: speak up after a period of user silence. Default false. |
| `turnDetectionTimeoutTime` | integer | nullable | Idle timeout in milliseconds; required when `turnDetectionTimeout` is true. |
| `turnDetectionInterruptResponse` | boolean | nullable | Let the user interrupt the AI. Default true. |
| `transcriptionModel` | string | nullable | `gpt-4o-transcribe` (default), `gpt-4o-mini-transcribe` or `off`. |
| `transcriptionLanguage` | string | nullable | ISO 639-1 code or `auto` (default). |
| `transcriptionInstructions` | string | nullable | Optional hints for the transcriber. |
| `noiseReductionType` | `none` \| `near_field` \| `far_field` | nullable | `near_field`, `far_field` (default) or `none`. |
| `toolAssignments` | AgentToolsConfigDto | nullable | Ignored; assign tools with `PUT /v1/tenants/{tenantId}/agents/{id}/tools` after creating the agent. |

### Responses

**201** — AgentDto: Created. The `Location` header points to the new agent.

| Field | Type | | Description |
| --- | --- | --- | --- |
| `id` | string | required | Agent id. |
| `version` | integer |  | Concurrency version. Send it back when updating; it increases on every update. |
| `name` | string | required | Display name. |
| `description` | string | nullable | Internal description for people; not given to the AI. |
| `instructions` | string | nullable | System prompt for the AI. May reference prompt variables as `{{name}}` (see `variableDefinitionsJson`) and system variables such as `{{system_caller_number}}`. |
| `variableDefinitionsJson` | string | nullable | Prompt variables as a JSON-encoded string: an array of `{"name", "jsonType", "placeholder", "description", "required"}`. Referenced as `{{name}}` in the instructions and filled at conversation time (e.g. from tool output); `placeholder` is used when no value is available. |
| `status` | `draft` \| `active` \| `archived` | nullable | Lifecycle status. |
| `model` | string | nullable | Realtime model, e.g. `gpt-realtime` or `gpt-realtime-1.5`. Empty means the platform default. |
| `voice` | `alloy` \| `ash` \| `ballad` \| `coral` \| `echo` \| `sage` \| `shimmer` \| `verse` \| `marin` \| `cedar` | nullable | Voice used for speech output. |
| `knowledgeBaseIds` | string[] | nullable | Ids of linked knowledge bases. |
| `phoneNumberId` | string | nullable | Id of the assigned phone number, if any. Change it with the agent phone-number endpoints. |
| `phoneNumber` | string | nullable | The assigned phone number in E.164 format (read only). |
| `allowFollowUpEmail` | boolean |  | Give the AI a `send_email` tool that emails conversation details to `followUpEmailAddress`. |
| `followUpEmailAddress` | string | nullable | Recipient of follow-up emails (e.g. a team inbox). Required when `allowFollowUpEmail` is true. |
| `allowCallTransfer` | boolean |  | Give the AI a `transfer_call` tool on phone calls. |
| `callTransferType` | CallTransferType |  | How phone calls are transferred. |
| `isTemplate` | boolean |  | When true the agent is a template that this tenant and its sub-tenants can create agents from. |
| `type` | string | nullable | Optional free-text label for your own classification; not used by the platform. |
| `allowEndCall` | boolean |  | Give the AI an `end_call` tool to end the conversation after saying goodbye. |
| `tenantId` | string | required | Tenant the agent belongs to (cannot be changed). |
| `turnDetectionType` | `server_vad` \| `semantic_vad` \| `none` | nullable | How the AI decides the user finished speaking: `server_vad` (silence based), `semantic_vad` (meaning based) or `none` (no automatic turn taking). |
| `turnDetectionEagerness` | `auto` \| `low` \| `medium` \| `high` | nullable | `semantic_vad` only: how quickly the AI responds. |
| `turnDetectionThreshold` | number (double) | nullable | `server_vad` only: speech detection sensitivity, 0.0–1.0 (higher needs louder speech). Default 0.5. |
| `turnDetectionPrefixPadding` | integer | nullable | `server_vad` only: milliseconds of audio kept before detected speech. Default 300. |
| `turnDetectionSilenceDuration` | integer | nullable | `server_vad` only: milliseconds of silence that end the user's turn. Default 500. |
| `turnDetectionTimeout` | boolean | nullable | `server_vad` only: when true, the AI speaks up after `turnDetectionTimeoutTime` of user silence. |
| `turnDetectionTimeoutTime` | integer | nullable | Idle timeout in milliseconds; required when `turnDetectionTimeout` is true. |
| `turnDetectionInterruptResponse` | boolean | nullable | Whether the user can interrupt the AI while it is speaking. Default true. |
| `transcriptionModel` | string | nullable | Speech-to-text model for transcripts: `gpt-4o-transcribe` (precision) or `gpt-4o-mini-transcribe` (speed). `off` disables transcription. |
| `transcriptionLanguage` | string | nullable | Expected language as an ISO 639-1 code (e.g. `sv`, `en`), or `auto` to detect. |
| `transcriptionInstructions` | string | nullable | Optional hints for the transcriber, e.g. product names or spelling. |
| `noiseReductionType` | `none` \| `near_field` \| `far_field` | nullable | Input noise reduction: `near_field` (headsets, phones), `far_field` (laptops, rooms) or `none`. |
| `toolAssignments` | AgentToolsConfigDto | nullable | Not filled here; use `GET /v1/tenants/{tenantId}/agents/{id}/tools`. |

**400**: Invalid follow-up email, or knowledge bases not in the agent's tenant (listed in `missing`).

**401**: Missing, invalid, revoked or expired API key.

**403**: The key lacks the required permission, or the tenant/resource is outside its reach.

**429**: Rate limit exceeded. Retry after the number of seconds in the Retry-After header.

### Example

```bash
curl -X POST "https://api.envocal.ai/v1/tenants/current/agents" \
  -H "Authorization: Bearer evk_eu_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"string"}'
```