POST /create-retell-llm — retell-sdk

Create a new Retell LLM Response Engine that can be attached to an agent. This is used to generate response output for the agent.

post/create-retell-llm

Request body

Available LLM models for agents.

s2s_model'gpt-realtime-2' | 'gpt-realtime-1.5' | 'gpt-realtime' | 'gpt-realtime-mini' | 'null' nullable

Select the underlying speech to speech model. Can only set this or model, not both.

model_temperaturenumber

If set, will control the randomness of the response. Value ranging from [0,1]. Lower value means more deterministic, while higher value means more random. If unset, default value 0 will apply. Note that for tool calling, a lower value is recommended.

model_high_priorityboolean nullable

If set to true, will use high priority pool with more dedicated resource to ensure lower and more consistent latency, default to false. This feature usually comes with a higher cost.

tool_call_strict_modeboolean nullable

Whether to use strict mode for tool calls. Only applicable when using certain supported models.

knowledge_base_idsstring[] nullable

A list of knowledge base ids to use for this resource.

start_speaker'user' | 'agent'

The speaker who starts the conversation. Required. Must be either 'user' or 'agent'.

begin_after_user_silence_msinteger nullable

If set, the AI will begin the conversation after waiting for the user for the duration (in milliseconds) specified by this attribute. This only applies if the agent is configured to wait for the user to speak first. If not set, the agent will wait indefinitely for the user to speak.

begin_messagestring nullable

First utterance said by the agent in the call. If not set, LLM will dynamically generate a message. If set to "", agent will wait for user to speak first.

general_promptstring nullable

General prompt appended to system prompt no matter what state the agent is in.

System prompt (with state) = general prompt + state prompt.
System prompt (no state) = general prompt.

starting_statestring nullable

Name of the starting state. Required if states is not empty.

default_dynamic_variablesobject nullable

Default dynamic variables represented as key-value pairs of strings. These are injected into your Retell LLM prompt and tool description when specific values are not provided in a request. Only applicable for Retell LLM.

Example request

{
  "s2s_model": "gpt-realtime-1.5",
  "model_high_priority": true,
  "tool_call_strict_mode": true,
  "kb_config": {
    "top_k": 3,
    "filter_score": 0.6
  },
  "begin_after_user_silence_ms": 2000,
  "begin_message": "Hey I am a virtual assistant calling from Retell Hospital.",
  "general_prompt": "You are ...",
  "general_tools": [
    {
      "type": "end_call",
      "name": "end_call",
      "description": "End the call with user."
    }
  ],
  "states": [
    {
      "name": "information_collection",
      "state_prompt": "You will follow the steps below to collect information...",
      "edges": [
        {
          "destination_state_name": "appointment_booking",
          "description": "Transition to book an appointment."
        }
      ],
      "tools": [
        {
          "type": "transfer_call",
          "name": "transfer_to_support",
          "description": "Transfer to the support team.",
          "transfer_destination": {
            "type": "predefined",
            "number": "16175551212",
            "ignore_e164_validation": false
          },
          "transfer_option": {
            "type": "cold_transfer",
            "show_transferee_as_caller": false
          }
        }
      ]
    },
    {
      "name": "appointment_booking",
      "state_prompt": "You will follow the steps below to book an appointment...",
      "tools": [
        {
          "type": "book_appointment_cal",
          "name": "book_appointment",
          "description": "Book an annual check up.",
          "cal_api_key": "cal_live_xxxxxxxxxxxx",
          "event_type_id": 60444,
          "timezone": "America/Los_Angeles"
        }
      ]
    }
  ],
  "starting_state": "information_collection",
  "default_dynamic_variables": {
    "customer_name": "John Doe"
  },
  "mcps": [
    {
      "headers": {
        "Authorization": "Bearer 1234567890"
      },
      "query_params": {
        "index": "1",
        "key": "value"
      }
    }
  ]
}

Response

Successfully created a new Retell LLM Response Engine.

llm_idstring required

Unique id of Retell LLM Response Engine.

versioninteger

Version of the Retell LLM Response Engine.

is_publishedboolean

Whether the Retell LLM Response Engine is published.