---
title: "Create a new agent"
method: POST
path: "/agent"
tags: ["Agents"]
---

# Create a new agent

`POST /agent`

Create a new agent by passing the agent name in the request body.

New agents have versioning enabled by default. To set the prompt,
`firstMessage`, tools, or any runtime config, fork a draft from the
auto-created initial version, edit it, publish, and activate — see
the [Versioning Lifecycle](/atoms/developer-guide/build/agents/versioning-lifecycle)
guide for the full flow.

The legacy `PATCH /workflow/{workflowId}` endpoint writes directly to
the underlying workflow document and bypasses the version lifecycle;
edits made that way are not captured as a version and may not
propagate to live calls. Use the drafts flow above.

## Request body

- CreateAgentRequest
  - `name` string, required
  - `description` string
  - `backgroundSound` '' | 'office' | 'cafe' | 'call_center' | 'static' — Ambient background sound during calls. Options: '' (none), 'office', 'cafe', 'call_center', 'static'. Note: this value is currently overridden by the server default on creation; update via PATCH after creation.
  - `language` object — Language configuration for the agent. Cross-field rule: `default` must be one of the values in `supported`. Tamil (`ta`) cannot be combined with other languages in `supported`.
    - `default` 'en' | 'hi' | 'mr' | 'gu' | 'ta' | 'es' | 'north_indic' | 'bn' | 'or' — The default language of the agent. Note: `ta` cannot be combined with other languages in `supported`.
    - `supported` string[] — Languages the agent understands. `default` must be one of these values. Tamil (`ta`) cannot be combined with other languages.
    - `switching` object — Language switching configuration for the agent. If enabled, the agent will be able to switch between languages based on the user's language.
      - `isEnabled` boolean — Whether to enable language switching for the agent
      - `minWordsForDetection` number — Minimum number of words required for language detection
      - `strongSignalThreshold` number — Threshold for strong language signal detection (0.1 to 0.9)
      - `weakSignalThreshold` number — Threshold for weak language signal detection (0.1 to 0.9)
      - `minConsecutiveForWeakThresholdSwitch` number — Minimum consecutive detections required for weak threshold language switch
  - `synthesizer` object — Synthesizer (TTS) configuration for the agent. Model `waves_lightning_v3_1` validates `voiceId` against the Waves API. `gpt-realtime` and `gpt-realtime-mini` accept any voiceId. Cloned voices are regular voiceIds. Use them with a compatible Waves model.
    - `voiceConfig` object — Voice configuration for the synthesizer.
      - `model` 'waves_lightning_v3_1' | 'gpt-realtime' | 'gpt-realtime-mini' — The TTS model to use. Use `waves_lightning_v3_1` for the recommended Waves voice path (default), or `gpt-realtime` / `gpt-realtime-mini` for OpenAI realtime models (require `workflowType: single_prompt`).
      - `voiceId` string — The voice ID to use. For cloned voices, pass the voiceId from the Waves platform with a compatible model.
      - `gender` 'male' | 'female' — The gender of the voice.
    - `speed` number
    - `consistency` number
    - `similarity` number
    - `enhancement` 0 | 1 | 2
    - `sampleRate` 8000 | 16000 | 24000 | 44100 — Output audio sample rate in Hz.
  - `globalKnowledgeBaseId` string — The global knowledge base ID of the agent. You can create a global knowledge base by using the /knowledgebase endpoint and assign it to the agent. The agent will use this knowledge base for its responses.
  - `slmModel` 'electron' | 'electron-kogta' | 'electron-kogta-v2' | 'gpt-4o' | 'gpt-4.1' | 'gpt-5.2' | 'gpt-realtime' | 'gpt-realtime-mini' — The LLM model to use for the agent. Note: `gpt-5.2`, `electron-kogta`, and `electron-kogta-v2` require org-level access and return 403 if not enabled. `workflowType` must be `single_prompt` to use `gpt-realtime` or `gpt-realtime-mini`.
  - `defaultVariables` object — The default variables to use for the agent. These variables will be used if no variables are provided when initiating a conversation with the agent.
  - `preCallAPI` object — Configuration for an API call to be made before the call starts. The response variables can be injected into the agent's prompt.
    - `isEnabled` boolean — Whether the pre-call API is enabled.
    - `url` string, uri, required — The URL of the API endpoint to call.
    - `method` 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH', required — The HTTP method to use for the API call.
    - `headers` object — Optional HTTP headers to include in the request.
    - `body` object — Optional request body for POST/PUT/PATCH requests.
    - `timeout` integer — Timeout in seconds for the API call.
    - `queryParams` object — Optional query parameters to include in the request URL.
    - `responseVariables` object[] — List of variables to extract from the API response using JSON path expressions.
      - `variableName` string, required — The name of the variable to inject into the agent prompt.
      - `jsonPath` string, required — JSON path expression to extract the value from the API response.
  - `globalPrompt` string — Set global instructions for your agent's personality, role, and behavior throughout conversations. Note: Only used for workflow_graph agents. Maximum 4000 characters.
  - `telephonyProductId` string[] — IDs of telephony products (phone numbers) to associate with the agent for inbound/outbound calls.
  - `workflowType` 'workflow_graph' | 'single_prompt' — The type of workflow configuration. workflow_graph uses a node-based visual workflow, single_prompt uses a simple prompt-based configuration.
  - `firstMessage` string — The first message the agent sends when a conversation starts.
  - `muteUserUntilFirstBotResponse` boolean — When true, the user's audio is muted until the agent has finished its first response.
  - `allowInterruptions` boolean — Whether the user can interrupt the agent while it is speaking.
  - `waitForUserToSpeakFirst` boolean — When true, the agent waits for the user to speak before sending the first message.
  - `interruptionBackoffTimer` number — Seconds the agent waits after being interrupted before resuming speech.
  - `smartTurnConfig` object — Smart turn-detection configuration. When enabled, the agent uses an additional model to decide whether the user has finished a turn.
    - `isEnabled` boolean
    - `waitTimeInSecs` number — How long to wait after the user stops speaking before responding.
  - `voiceDetectionConfig` object — Voice activity detection (VAD) configuration. Controls how the agent decides when speech is present.
    - `confidence` number — Minimum VAD confidence threshold to register speech.
    - `minVolume` number — Minimum input volume threshold to register speech.
    - `triggerTimeInSecs` number — How long sustained speech must be detected before turning the VAD on.
    - `releaseTimeInSecs` number — How long after silence before the VAD turns off.
  - `voiceMailDetectionConfig` object — Voicemail-detection configuration. When the call hits a voicemail tone, the agent plays `endText` and ends the call.
    - `enabled` boolean
    - `endText` string — Message played before hanging up when voicemail is detected.
  - `denoisingConfig` object — Background-noise denoising configuration for the agent's input audio.
    - `isEnabled` boolean
  - `redactionConfig` object — PII redaction configuration. When enabled, personally identifiable information is redacted from transcripts before storage.
    - `isEnabled` boolean
  - `pronunciationDicts` object[] — Pronunciation overrides — words the TTS engine should pronounce differently from its default.
    - `word` string, required — The word to override.
    - `pronunciation` string, required — How the word should be pronounced (phonetic spelling).
  - `llmIdleTimeoutConfig` object — Timeout configuration for the LLM stage of a conversation. Triggers a retry or call termination when the LLM does not respond within the configured window.
    - `chatTimeoutTimeInSecs` number — LLM idle timeout for chat conversations, in seconds.
    - `webcallTimeoutTimeInSecs` number — LLM idle timeout for web calls, in seconds.
    - `telephonyTimeoutTimeInSecs` number — LLM idle timeout for telephony calls, in seconds.
    - `maxRetries` number — Maximum number of LLM-idle retries before terminating the call. System-defined min/max.
  - `sessionTimeoutConfig` object — Maximum duration of a conversation session. The call ends after this elapsed time even if active.
    - `timeoutTimeInSecs` number — Maximum session duration in seconds (max 1 hour). Defaults to 1800 (30 minutes).
  - `timezone` object — Timezone applied to scheduled actions and timestamps the agent reports to the user.
    - `label` string — IANA timezone label (e.g. `America/New_York`).
    - `offset` number — UTC offset in minutes (e.g. -300 for EST).
  - `callDispositionConfig` string — Configuration string for call disposition tracking.
  - `allowInboundCall` boolean — Whether the agent accepts inbound calls.
  - `enableStyleGuide` boolean — Whether style guide enforcement is applied to agent responses.
  - `speechFormatting` boolean — Whether speech formatting is applied to the agent's responses.

## Response `201`

Agent created successfully

- object
  - `status` boolean
  - `data` string — The ID of the created agent

## Other responses

- `400` — Invalid input
- `401` — Unauthorized access
- `403` — Forbidden access
- `500` — Internal server error

---

[API](https://skmtc.net/smallest-inc/apis/agent-management-api.md) · [All operations](https://skmtc.net/smallest-inc/apis/agent-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smallest-inc/agent-management-api/versions/6d1036a76fbc/schema)