--- title: "Create Agent" method: POST path: "/agents" --- # Create Agent `POST /agents` ## Request - Base URL: `https://api.vogent.ai/api` - URL: `https://api.vogent.ai/api/agents` - Auth: HTTP bearer Creates a new agent. ## Request body - CreateAgentInput - `name` string, required: The name of the agent. - `defaultVoiceId` string, required: The ID of the voice to use. - `defaultVersionedPrompt` CreateVersionedPromptInput, required - `aiModelId` string, required: The ID of the model to use. - `agentType` 'STANDARD' | 'CUSTOM_FLOW', required - `prompt` string, nullable - `flowDefinition` FlowDefinitionInput - `nodes` ApiFlowNodeInput[] - `id` string, required - `name` string, required: One of the allowed flow node types. View the available types at https://docs.vogent.ai/flow. - `type` string, required - `transitionRules` FlowTransitionRuleInput[], required - `conditionType` 'always' | 'equal' | 'in' | 'greater' | 'less' | 'language', required: The condition used to evaluate the transition rule. If language, the value will be used as a natural language condition to describe when to execute a transition. - `arrayConditionType` 'any' | 'all', nullable: The type of array condition to apply. 'any' means at least one element must match, 'all' means all elements must match. - `field` string, nullable - `value` string, nullable - `values` string[], nullable - `transitionNodeId` string, required - `nodeData` object, required: The node-specific configuration. View the configurations by node type at https://docs.vogent.ai/flow. - `globalContext` string, nullable - `aiOpen` boolean: Deprecated, use openingLineType instead. - `openingLineType` 'INBOUND_ONLY' | 'INBOUND_OUTBOUND' | 'NONE' - `name` string, required - `modelOptionValues` ModelOptionValue[] - `optionId` string, required: The ID of option. - `value` string, required - `defaultExtractor` CreateCallAgentExtractorInput - `name` string, required - `extractorFieldsJsonSchema` string, required - `inboundWebhookResponse` boolean - `inboundWebhookUrl` string - `maxDurationSeconds` integer: The maximum duration of the call in seconds. - `timeoutMessage` string, nullable: An optional message to play via TTS before hanging up when the call reaches its max duration timeout. - `timeoutBehaviorConfiguration` TimeoutBehaviorConfiguration, nullable - `behavior` 'HANGUP' | 'TRANSFER', required: The behavior when a call reaches its max duration timeout. HANGUP disconnects the call, TRANSFER forwards to a specified number. - `transferNumber` string, nullable: The phone number to transfer to when behavior is TRANSFER. - `openingLine` object, nullable: Details about the Agent's opening line. If unspecified, or null no opening line will be created. - `lineType` 'INBOUND_ONLY' | 'INBOUND_OUTBOUND' | 'NONE', required - `content` string, required: The content of the opening line. - `voiceVolumeLevel` integer, nullable: A value, generally between -300 and 300, indicating the volume level to use for the voice. The default is -100. - `backgroundNoiseType` 'noise' | 'office' | 'silence': The background audio that's used by the agent. - `linkedFunctionDefinitionIds` string[]: The function definitions that should be available to this agent (deprecated, use linkedFunctionDefinitionInputs instead) - `linkedFunctionDefinitionInputs` LinkedFunctionDefinition[]: The function definitions that should be available to this agent with optional lifecycle message overrides - `functionDefinitionId` string, required: The ID of the function definition to link. - `lifecycleMessagesOverride` FunctionLifecycleMessages - `started` string[], required: Messages to display when the function starts executing. One will be chosen at random. - `waiting` string[]: Messages to play while the function is still running and the model returned StillWaiting. One will be chosen at random. If empty, a built-in default set of English phrases is used. - `awaitSpeech` boolean: Hold the function until the agent has finished speaking — any text said alongside the call, then the started message — instead of running it while the agent is still talking. Defaults to false. - `metadata` object - `transcriberParams` TranscriberParams - `type` string, required: By default, the only supported option is deepgram. Please contact support if you'd like access to more options. - `keywords` string[]: Keywords to be used for transcription. - `idleMessageConfig` IdleMessageConfig - `enabled` boolean, required: Whether idle messages are enabled for this agent. - `messages` string[]: The list of idle messages that the agent can say when the user is silent. - `idleDurationMilliseconds` integer: The duration in milliseconds that the user must be silent before an idle message is triggered. - `maxIdleMessages` integer: The maximum number of idle messages that can be said during a call. - `utteranceDetectorConfig` UtteranceDetectorConfig - `sensitivity` 'ULTRA_FAST' | 'FAST' | 'MEDIUM' | 'SLOW', required - `interruptionPlayTimeMs` integer, nullable: The minimum amount of time in milliseconds that the agent will continue speaking after being interrupted. Defaults to 0. - `endpointDetectorConfig` EndpointDetectorConfig - `type` 'SIMPLE' | 'SEMANTIC', required - `mode` 'CONSERVATIVE' | 'DEFAULT' | 'AGGRESSIVE' - `ivrConfiguration` IVRConfiguration, nullable - `detectionType` 'NONE' | 'STANDARD', required: The type of IVR detection to use for the agent. - `versionedPromptId` string, nullable: The versioned prompt ID to use for IVR detection. - `aiVoiceId` string, nullable: The AI voice ID to use for IVR detection. - `taggingText` string, nullable: The tagging text for IVR detection. - `language` string: The language to use for the agent. - `secondaryLanguages` string[]: Additional languages the agent can switch to during a call. - `enableChangeLanguage` boolean: Whether the agent can use the change_language tool to switch languages during a call. - `fillEmptyStringVariables` boolean, nullable: If true, variables that are not specified will be filled with empty strings instead of being left as template placeholders. - `silenceHangupConfiguration` SilenceHangupConfiguration, nullable - `type` 'DISABLED' | 'FIRST_MESSAGE_ONLY' | 'WHOLE_CALL', required: The type of silence hangup behavior. DISABLED means no silence hangup, FIRST_MESSAGE_ONLY means only hangup if no first message is received, WHOLE_CALL means hangup after silence at any point in the call. - `silenceDurationSeconds` integer: The duration of silence in seconds before hanging up. - `ivrSilenceHangupConfiguration` SilenceHangupConfiguration, nullable - `type` 'DISABLED' | 'FIRST_MESSAGE_ONLY' | 'WHOLE_CALL', required: The type of silence hangup behavior. DISABLED means no silence hangup, FIRST_MESSAGE_ONLY means only hangup if no first message is received, WHOLE_CALL means hangup after silence at any point in the call. - `silenceDurationSeconds` integer: The duration of silence in seconds before hanging up. - `voicemailConfig` VoicemailConfig, nullable - `detection` 'DISABLE' | 'HANGUP' | 'LEAVE_VOICEMAIL', required: How the agent reacts to an answering machine. DISABLE disables voicemail detection, HANGUP ends the call on detection, LEAVE_VOICEMAIL waits for the beep and speaks the configured message before hanging up. - `message` string, nullable: The text to speak via TTS when leaving a voicemail. Required when detection is LEAVE_VOICEMAIL. - `voiceOptionValues` ModelOptionValue[]: An optional configuration for the voice being used. - `optionId` string, required: The ID of option. - `value` string, required ## Response `200` Successful operation - Agent - `id` string, required - `name` string, required - `transcriberParams` TranscriberParams - `type` string, required: By default, the only supported option is deepgram. Please contact support if you'd like access to more options. - `keywords` string[]: Keywords to be used for transcription. - `metadata` object - `utteranceDetectorConfig` UtteranceDetectorConfig - `sensitivity` 'ULTRA_FAST' | 'FAST' | 'MEDIUM' | 'SLOW', required - `interruptionPlayTimeMs` integer, nullable: The minimum amount of time in milliseconds that the agent will continue speaking after being interrupted. Defaults to 0. - `endpointDetectorConfig` EndpointDetectorConfig - `type` 'SIMPLE' | 'SEMANTIC', required - `mode` 'CONSERVATIVE' | 'DEFAULT' | 'AGGRESSIVE' - `ivrConfiguration` IVRConfiguration, nullable - `detectionType` 'NONE' | 'STANDARD', required: The type of IVR detection to use for the agent. - `versionedPromptId` string, nullable: The versioned prompt ID to use for IVR detection. - `aiVoiceId` string, nullable: The AI voice ID to use for IVR detection. - `taggingText` string, nullable: The tagging text for IVR detection. - `idleMessageConfig` IdleMessageConfig - `enabled` boolean, required: Whether idle messages are enabled for this agent. - `messages` string[]: The list of idle messages that the agent can say when the user is silent. - `idleDurationMilliseconds` integer: The duration in milliseconds that the user must be silent before an idle message is triggered. - `maxIdleMessages` integer: The maximum number of idle messages that can be said during a call. - `language` string, required: The language to use for the agent. - `maxDurationSeconds` integer: The maximum duration of the call in seconds. - `timeoutMessage` string, nullable: An optional message to play via TTS before hanging up when the call reaches its max duration timeout. - `timeoutBehaviorConfiguration` TimeoutBehaviorConfiguration, nullable - `behavior` 'HANGUP' | 'TRANSFER', required: The behavior when a call reaches its max duration timeout. HANGUP disconnects the call, TRANSFER forwards to a specified number. - `transferNumber` string, nullable: The phone number to transfer to when behavior is TRANSFER. - `defaultVoiceId` string: The default voice ID to use for the agent. - `defaultVersionedPromptId` string: The default versioned prompt ID to use for the agent. - `defaultExtractorId` string, nullable: The default extractor ID to use for the agent. - `linkedFunctionDefinitions` LinkedFunctionDefinition[]: The function definitions that should be available to this agent. - `functionDefinitionId` string, required: The ID of the function definition to link. - `lifecycleMessagesOverride` FunctionLifecycleMessages - `started` string[], required: Messages to display when the function starts executing. One will be chosen at random. - `waiting` string[]: Messages to play while the function is still running and the model returned StillWaiting. One will be chosen at random. If empty, a built-in default set of English phrases is used. - `awaitSpeech` boolean: Hold the function until the agent has finished speaking — any text said alongside the call, then the started message — instead of running it while the agent is still talking. Defaults to false. - `fillEmptyStringVariables` boolean: If true, variables that are not specified will be filled with empty strings instead of being left as template placeholders. - `silenceHangupConfiguration` SilenceHangupConfiguration, nullable - `type` 'DISABLED' | 'FIRST_MESSAGE_ONLY' | 'WHOLE_CALL', required: The type of silence hangup behavior. DISABLED means no silence hangup, FIRST_MESSAGE_ONLY means only hangup if no first message is received, WHOLE_CALL means hangup after silence at any point in the call. - `silenceDurationSeconds` integer: The duration of silence in seconds before hanging up. - `ivrSilenceHangupConfiguration` SilenceHangupConfiguration, nullable - `type` 'DISABLED' | 'FIRST_MESSAGE_ONLY' | 'WHOLE_CALL', required: The type of silence hangup behavior. DISABLED means no silence hangup, FIRST_MESSAGE_ONLY means only hangup if no first message is received, WHOLE_CALL means hangup after silence at any point in the call. - `silenceDurationSeconds` integer: The duration of silence in seconds before hanging up. - `voicemailConfig` VoicemailConfig, nullable - `detection` 'DISABLE' | 'HANGUP' | 'LEAVE_VOICEMAIL', required: How the agent reacts to an answering machine. DISABLE disables voicemail detection, HANGUP ends the call on detection, LEAVE_VOICEMAIL waits for the beep and speaks the configured message before hanging up. - `message` string, nullable: The text to speak via TTS when leaving a voicemail. Required when detection is LEAVE_VOICEMAIL. - `voiceOptionValues` ModelOptionValue[]: The configuration values for the voice being used by the agent. - `optionId` string, required: The ID of option. - `value` string, required ## Other responses - `400`: Invalid input - `422`: Validation exception --- [API](https://skmtc.dev/vogent/apis/vogent-openapi-3-0.md) - [All operations](https://skmtc.dev/vogent/apis/vogent-openapi-3-0/llms.txt) - [OpenAPI document](https://skmtc.dev/vogent/apis/vogent-openapi-3-0/revisions/a5966cc364ef?raw)