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

# Create Agent

`POST /v1/agents`

Create a new agent.

An agent represents an AI persona (Support Bot, Sales Agent, etc.)
that can have phone numbers attached to it.

voiceMode: "webhook" (default) forwards transcripts to your webhook.
           "hosted" uses a built-in LLM with systemPrompt (no webhook needed).

## Request body

- CreateAgentRequest
  - `name` string, required
  - `description` string, nullable
  - `voiceMode` 'webhook' | 'hosted', nullable
  - `enableMessaging` boolean, nullable — When true, hosted-mode agents can send and read SMS/iMessage during calls. Defaults to true.
  - `modelTier` 'turbo' | 'balanced' | 'max', nullable
  - `systemPrompt` string, nullable
  - `beginMessage` string, nullable
  - `voice` string, nullable
  - `transferNumber` string, nullable
  - `customTools` CustomToolParam[], nullable — Hosted-mode only. User-defined function tools the agent can call during a call (look up a record, save call notes, etc.). Each points at your HTTPS endpoint; the voice provider invokes it and feeds the JSON response back to the agent. Ignored in webhook mode. Maximum 20 tools.
    - `name` string, required — Function name the agent calls. Letters, numbers, underscores, hyphens; max 64 chars. Must be unique and not a reserved built-in name.
    - `description` string, required — What the tool does and when to use it. The agent relies on this to decide when to call it.
    - `url` string, required — HTTPS endpoint the voice provider calls when the agent invokes this tool.
    - `method` 'GET' | 'POST', nullable — HTTP method. Defaults to POST.
    - `headers` object, nullable — Optional HTTP headers sent with the request (e.g. an Authorization token for your endpoint).
    - `parameters` object, nullable — JSON Schema object describing the arguments the agent fills in. Omit for a no-argument tool.
    - `timeoutMs` integer, nullable — How long to wait for your endpoint before giving up. Range 1000-120000 ms.
    - `speakDuringExecution` boolean, nullable — When true, the agent speaks executionMessage while the tool runs.
    - `executionMessage` string, nullable — What the agent says while the tool runs (used when speakDuringExecution is true).
  - `voicemailMessage` string, nullable
  - `callScreeningIdentity` string, nullable
  - `callScreeningPurpose` string, nullable
  - `sttMode` 'fast' | 'accurate', nullable — Speech-to-text mode. 'fast' optimizes for latency, 'accurate' optimizes for transcription accuracy (~200ms additional latency).
  - `ambientSound` 'none' | 'office' | 'coffee-shop' | 'outdoor', nullable — Background ambience to mask synthetic silence between turns. 'none' disables; 'office', 'coffee-shop', 'outdoor' enable a quiet bed.
  - `denoisingMode` 'noise-cancellation' | 'noise-and-background-speech-cancellation', nullable — Audio denoising. 'noise-cancellation' (default) handles general noise. 'noise-and-background-speech-cancellation' is more aggressive for callers in cars, cafes, or near TVs ($0.005/min surcharge).
  - `maxSilenceMs` integer, nullable — Hang up the call after this many milliseconds of caller silence. Default 600000 (10 min). Raise for IVR/hold-music workflows; lower to fail fast on dead lines. Range 10000 (10s) to 3600000 (1 hour).
  - `voiceSpeed` number, nullable — Voice speed multiplier. 1.0 is normal pace; lower values slow speech (0.5 is half speed), higher values speed it up (2.0 is double). Range 0.5 to 2.0.
  - `interruptionSensitivity` number, nullable — How easily callers can interrupt the agent. 0 means the agent is never interrupted, 1 means the agent stops at the first sound. Default 0.8. Range 0.0 to 1.0.
  - `enableBackchannel` boolean, nullable — When true, the agent interjects short filler words like 'uh-huh' or 'mhmm' during longer caller utterances. Set false to keep the agent silent while the caller is speaking. Defaults to true.
  - `language` 'af-ZA' | 'ar-SA' | 'az-AZ' | 'bg-BG' | 'bs-BA' | 'ca-ES' | 'cs-CZ' | 'cy-GB' | 'da-DK' | 'de-DE' | 'el-GR' | 'en-AU' | 'en-GB' | 'en-IN' | 'en-NZ' | 'en-US' | 'es-419' | 'es-ES' | 'fa-IR' | 'fi-FI' | 'fil-PH' | 'fr-CA' | 'fr-FR' | 'gl-ES' | 'he-IL' | 'hi-IN' | 'hr-HR' | 'hu-HU' | 'hy-AM' | 'id-ID' | 'is-IS' | 'it-IT' | 'ja-JP' | 'kk-KZ' | 'kn-IN' | 'ko-KR' | 'lt-LT' | 'lv-LV' | 'mk-MK' | 'mr-IN' | 'ms-MY' | 'ne-NP' | 'nl-BE' | 'nl-NL' | 'no-NO' | 'pl-PL' | 'pt-BR' | 'pt-PT' | 'ro-RO' | 'ru-RU' | 'sk-SK' | 'sl-SI' | 'sr-RS' | 'sv-SE' | 'sw-KE' | 'ta-IN' | 'th-TH' | 'tr-TR' | 'uk-UA' | 'ur-IN' | 'vi-VN' | 'yue-CN' | 'zh-CN', nullable — BCP-47 locale that drives the agent's speech recognition and pronunciation. Defaults to 'en-US'. See the enum for the full set of supported codes.

## Response `200`

Successful Response

- AgentResponse
  - `id` string, required
  - `name` string, required
  - `description` string, nullable, required
  - `voiceMode` 'webhook' | 'hosted', required
  - `enableMessaging` boolean
  - `modelTier` 'turbo' | 'balanced' | 'max'
  - `systemPrompt` string, nullable
  - `beginMessage` string, nullable
  - `voice` string, required
  - `transferNumber` string, nullable
  - `customTools` object[], nullable
  - `voicemailMessage` string, nullable
  - `callScreeningIdentity` string, nullable
  - `callScreeningPurpose` string, nullable
  - `sttMode` 'fast' | 'accurate' — Speech-to-text mode. 'fast' optimizes for latency, 'accurate' optimizes for transcription accuracy (~200ms additional latency).
  - `ambientSound` 'none' | 'office' | 'coffee-shop' | 'outdoor' — Background ambience to mask synthetic silence between turns. 'none' disables; 'office', 'coffee-shop', 'outdoor' enable a quiet bed.
  - `denoisingMode` 'noise-cancellation' | 'noise-and-background-speech-cancellation' — Audio denoising. 'noise-cancellation' (default) handles general noise. 'noise-and-background-speech-cancellation' is more aggressive for callers in cars, cafes, or near TVs ($0.005/min surcharge).
  - `maxSilenceMs` integer — Hang up the call after this many milliseconds of caller silence. Range 10000 (10s) to 3600000 (1 hour). Default 600000 (10 min).
  - `voiceSpeed` number — Voice speed multiplier. Range 0.5 to 2.0. Default 1.0.
  - `interruptionSensitivity` number — How easily callers can interrupt the agent. Range 0.0 to 1.0. Default 0.8.
  - `enableBackchannel` boolean — When true, the agent interjects short filler words like 'uh-huh' or 'mhmm' during longer caller utterances. Defaults to true.
  - `language` string — BCP-47 locale that drives the agent's speech recognition and pronunciation. Defaults to 'en-US'.
  - `createdAt` string, date-time, required
  - `numbers` AgentNumberResponse[], nullable
    - `id` string, required
    - `phoneNumber` string, required
    - `status` string, required
    - `type` string

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/agentphone/apis/agentphone-api.md) · [All operations](https://skmtc.net/agentphone/apis/agentphone-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agentphone/agentphone-api/versions/3f3aa65dcd20/schema)