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

# Create

`POST /agents`

Creates a new agent in a project.

## Query parameters

- `project` string

## Headers

- `Authorization` string, required

## Request body

- CreateAgentRequest
  - `name` string, required — The name of the agent. Can only contain lowercase letters, numbers and hyphens. Must be unique within the project.
  - `slug` string — URL-friendly agent slug. Can only contain lowercase letters, numbers and hyphens. Must be unique within the project.
  - `phone_number` 'assign-automatically' | 'custom' — When set to `null`, the agent will not be associated with a phone number. When set to `"assign-automatically"`, the agent will be assigned a random phone number. When set to `"custom"`, you must provide `custom_phone_numbers`.
  - `custom_phone_number` string, nullable — The custom phone number to use for the agent in E.164 format (e.g., +1234567890). This field is deprecated. Use `custom_phone_numbers` instead.
  - `custom_phone_numbers` string[] — Array of custom phone numbers in E.164 format (e.g., ["+1234567890", "+0987654321"]). The agent will be able to receive phone calls on any of these numbers. Required when `phone_number` is set to `"custom"`. All phone numbers must be unique.
  - `timezone` string — The timezone of the agent. Used to format system variables like `{{system_time}}`.
  - `voice_id` string — The voice ID to use.
  - `audio_format` 'pcm_44100' | 'pcm_24000' | 'pcm_16000' | 'pcm_8000' | 'mulaw_8000' — The audio format of the agent.
  - `audio_speed` number, double — The audio speed of the agent.
  - `background_noise_level` number, double — The background noise level of the agent.
  - `background_noise` 'office' | 'call-center' | 'coffee-shop' — The background noise type. Can be "office", "call-center", "coffee-shop", or null.
  - `generate_welcome_message` boolean — When `true`, the welcome message will be automatically generated and the `welcome_message` field will be ignored.
  - `is_welcome_message_interruptible` boolean — When `false`, the welcome message will not be interruptible by the user.
  - `websocket_timeout_sec` integer — Number of seconds of inactivity before the conversation WebSocket is closed.
  - `welcome_message` string, nullable — Message to play when the conversation starts. Can contain template variables like `{{customer_name}}`. Ignored when `generate_welcome_message` is `true`.
  - `system_prompt` string — Instructions for the conversation. Can contain template variables like `{{subject}}`.
  - `template_variables` object — Variables that can be used in the welcome message and the system prompt.
  - `tools` CreateAgentRequestToolsItems[] — Array of built-in or custom tool names to use.
    - union
      - 'keypad_input' | 'natural_conversation_ending' | 'choose_not_to_respond' — Built-in tool
      - string
  - `built_in_tool_configs` union
    - BuiltInToolConfig — Configuration for a simple built-in tool (`keypad_input` or `natural_conversation_ending`).
      - `speech_before_tool_call` 'required' | 'optional' | 'suppressed', required — Controls whether the assistant speaks before the tool is called. `required`: the assistant must speak first. `optional`: the model decides. `suppressed`: the assistant is strongly instructed to stay silent before the call (best effort).
    - ChooseNotToRespondToolConfig — Configuration for the `choose_not_to_respond` built-in tool.
      - `respond_after_sec` number, double, nullable — Number of seconds to wait after the tool fires before the assistant speaks a follow-up if the user stays silent. When null, the assistant stays silent (default).
  - `tasks` Task[] — Array of task objects with `name` and `description` fields.
    - `name` string, required — The name of the task.
    - `description` string, required — The description of the task.
  - `generate_no_input_poke_text` boolean — Whether to have the no-input poke text be generated by AI.
  - `no_input_poke_sec` integer, nullable — Number of seconds of silence before sending a poke message. `null` disables the poke message.
  - `no_input_poke_text` string — The message to send after the specified silence. Ignored when generate_no_input_poke_text is true.
  - `no_input_end_conversation_sec` integer — Seconds of silence before ending the conversation.
  - `enable_assistant_backchannel` boolean — When `true`, the assistant will produce backchannel responses (e.g. "mm-hmm") while the user is speaking.
  - `assistant_backchannel_aggressiveness` number, double — How aggressively the assistant produces backchannel responses. Only relevant when `enable_assistant_backchannel` is `true`.
  - `data_retention_policy` union — Controls how long transcripts and audio recordings are retained before deletion. When `zero_data_retention` is `true`, nothing is retained and `transcripts`/`audio_recordings` are omitted.
    - DataRetentionPolicy0 — Zero data retention mode. No transcripts or audio recordings are retained.
      - `zero_data_retention` boolean, required — When `true`, no transcripts or audio recordings are retained.
    - DataRetentionPolicy1 — Standard data retention with configurable deletion windows.
      - `zero_data_retention` boolean, required — Must be `false` for standard data retention.
      - `transcripts` DataRetentionPolicyOneOf1Transcripts, required
        - `delete_after_hours` integer, nullable, required — Number of hours after which transcripts are deleted. Null means transcripts are retained indefinitely.
      - `audio_recordings` DataRetentionPolicyOneOf1AudioRecordings, required
        - `delete_after_hours` integer, nullable, required — Number of hours after which audio recordings are deleted. Null means audio recordings are retained indefinitely.
  - `default_language` 'ar' | 'az' | 'bg' | 'bn' | 'cs' | 'da' | 'de' | 'el' | 'en' | 'es' | 'fa' | 'fi' | 'fil' | 'fr' | 'gu' | 'he' | 'hi' | 'hu' | 'id' | 'it' | 'ja' | 'ka' | 'km' | 'kn' | 'ko' | 'lt' | 'lv' | 'ml' | 'mr' | 'ms' | 'ne' | 'nl' | 'no' | 'pa' | 'pl' | 'pt' | 'ro' | 'ru' | 'si' | 'sk' | 'sq' | 'sv' | 'sw' | 'ta' | 'te' | 'th' | 'tr' | 'uk' | 'ur' | 'vi' | 'yue' | 'zh' — ISO 639-1 language codes supported by the agent
  - `additional_languages` LanguageCode[] — Array of additional ISO 639-1 language codes that the agent should be able to recognize and speak. Should not include `default_language`. When `multilingual_mode` is `"auto"`, a maximum of 2 additional languages is allowed.
  - `languages` LanguageCode[] — Array of ISO 639-1 language codes that the agent should be able to recognize. This field is deprecated. Use `default_language` and `additional_languages` instead.
  - `multilingual_mode` 'auto' | 'request' | 'initial' — If `"auto"`, each user audio is automatically identified for the language to respond in. If `"request"`, user must request to change language (recommended). If `"initial"` the first turn user audio determines the language for the rest of the conversation.
  - `push_to_talk` boolean — Push to talk mode. User must send mute/unmute messages to turn on/off listening to audio. Defaults to false.
  - `intelligence_level` 'standard' | 'high' — The intelligence level of the agent. `high` uses a more capable model for more complex reasoning, while `standard` is optimized for lower latency.
  - `boosted_keywords` string[] — These words, or short phrases, will be more accurately recognized by the agent.
  - `pronunciation_dictionary` CreateAgentRequestPronunciationDictionaryItems[] — Array of `{ word, pronunciation }` entries. Words must be unique.
    - `word` string, required
    - `pronunciation` string, required
  - `min_words_to_interrupt` integer — Minimum number of words required to interrupt the assistant.
  - `configuration_endpoint` CreateAgentRequestConfigurationEndpoint — When not `null`, at the beginning of the conversation the agent will make a POST request to this endpoint to get configuration options.
    - `url` string, required — URL to call. Must be a publicly routable HTTPS URL without embedded credentials.
    - `headers` object — Object of key-value pairs.
    - `timeout_ms` integer — Timeout in milliseconds for the endpoint call.
  - `inbound_rollout` number, double — Float between 0.0 and 1.0 representing the percentage of inbound calls handled by Agent. Defaults to `1.0`. Requires `phone_number` to be set when less than 1.0.
  - `inbound_rollout_forward_phone_number` string, nullable — E.164 formatted phone number where non-agent calls will be forwarded. Required when `inbound_rollout < 1.0`, must be `null` when `inbound_rollout = 1.0`. Defaults to `null`.
  - `vad_prebuffer_duration_ms` integer — Voice activity detection prebuffer duration in milliseconds.
  - `vad_min_speech_duration_ms` integer — Minimum speech duration for voice activity detection in milliseconds.
  - `vad_min_silence_duration_ms` integer — Minimum silence duration for voice activity detection in milliseconds.
  - `vad_threshold` number, double — Voice activity detection threshold.
  - `enable_redaction` boolean — When `true`, PII and PHI are redacted from text transcripts (e.g. replaced with tags like `[PHONE]`) and bleeped from audio recordings after the conversation ends.
  - `mcp_server_ids` string[] — Array of MCP server IDs to make available to the agent.
  - `observability_integrations` CreateAgentRequestObservabilityIntegrationsItems[] — Names of observability integrations to enable for the agent. Each must be one of the supported providers.
  - `external_storage_policy` string, nullable — Name of an external storage policy in the same project that conversation artifacts are delivered to. Requires zero data retention and cannot be combined with `enable_redaction`.

## Response `201`

Success response

- AgentsCreateResponse201
  - `id` string, required — The ID of the created agent.
  - `name` string, required — The name of the created agent.

## Other responses

- `400` — Invalid parameters
- `401` — Unauthorized (authentication missing or invalid)
- `404` — Project not found
- `500` — Internal server error

---

[API](https://skmtc.net/phonic/apis/api-reference.md) · [All operations](https://skmtc.net/phonic/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/phonic/api-reference/revisions/7f8c81a5a990/schema)