Start an ephemeral session
Updated
Starts a session with an agent configuration that you pass in the request.
Preview documentation
https://preview.ai.agora.io/conversational-ai/v1/projects/{appid}/sessions/ephemeralUse this endpoint to start a session without saving an agent first, for example to test a configuration. The request body is the same as Start a session, but with the agent configuration in agent instead of agent_id. The configuration isn't saved.
appidstringThe App ID of your project.
Idempotency-KeystringA unique key, so that retrying the request can't start a second session. If a session was already started with this key, the request fails with 409 and reason IdempotencyKeyConflict, and no new session starts. The API doesn't return the original response. To find the session, list sessions. Keep the same key when you retry; never switch keys.
agentobjectThe agent configuration for this session. It has the same fields as Create an agent, except agent_name. The configuration isn't saved.
instructionsstringThe system instructions that define how the agent behaves. The model receives them as the first system message, before messages.
messagesarray<object>Messages that start the conversation history. They follow instructions.
rolestringThe author of the message:
system: An instruction to the model.user: A message from the user.assistant: A message from the agent.
contentstringThe text of the message.
variablesobjectEvery variable the agent uses, keyed by variable name. A name starts with a lowercase letter and contains up to 64 lowercase letters, digits, and underscores. Reference a variable as {{variable_name}} in instructions, messages, greeting.text, pipeline.llm.failure_message, pipeline.silence_config.content, and generated filler instructions. The agent doesn't store values: pass them in values when you start a session, or in each campaign contact. Expansion is single-pass, so a value that contains a placeholder isn't expanded again.
[key: string]objecttypestringThe data type of the variable value. Pass date and datetime values as ISO 8601 strings, for example "2026-09-30" and "2026-09-30T14:00:00Z".
requiredbooleanWhether a value is required in values when you start a session, or in each campaign contact. If a required value is missing, the session or the contact is rejected with MissingRequiredField.
optionsarray<string | number | boolean>The allowed values, 1 to 100 unique items of the declared type. Values you supply must be one of them, and extraction chooses one of them.
extractbooleanWhether to extract this variable from the transcript after the session ends. The Preview API doesn't return the extracted values. When true, description is required. An agent can have up to 50 extract variables.
descriptionstringWhat the variable means. Required when extract is true, where it serves as the extraction instruction.
greetingobjectThe message the agent speaks when a participant joins. If you omit it, the agent doesn't greet participants automatically.
modestringtext: The agent speaks text using the TTS stage.
onstringWhich participants the agent greets:
each_join: Every participant who joins.first_join: Only the first participant to join.
delay_msintegerThe delay in milliseconds between a participant joining and the agent starting the greeting.
textstringThe greeting text.
pipelineobjectThe models that power the agent: separate ASR, LLM, and TTS stages. When you pass a pipeline, llm and tts are required.
modestringcascaded: Separate ASR, LLM, and TTS stages.
asrobjectThe automatic speech recognition (ASR) stage, which transcribes the user's speech.
credentialManaged | BYOKHow this stage authenticates with the provider. Set it explicitly on each stage. Pass the fields of one credential mode only. Responses return only mode.
modestring(Managed)managed: Agora provides the provider authentication.
modestring(BYOK)byok: You pass your own provider credentials.
fieldsobject(BYOK)Your provider credentials, keyed by the provider's field name. Most providers take one field, api_key. Some use other names, such as key or credentials, or take more than one field, such as an AWS access key ID and secret access key. Each model page lists its provider's fields. In an agent, each value must be a $secrets.<set_name>.<key> reference to a secret set. An ephemeral session also accepts the values themselves. Agora resolves references when each session starts. The values are never returned.
[key: string]stringvendorstringThe ASR provider, for example deepgram.
modelstringThe provider model, for example nova-3.
languagestringThe language of the user's speech, for example en-US.
urlstringA custom provider endpoint. Don't also put the endpoint in params.
paramsobjectProvider-specific settings that aren't secret, such as keywords, passed to the provider as they are. Keep API keys in credential, not here.
llmobjectThe large language model (LLM) stage, which generates the agent's replies.
credentialManaged | BYOKHow this stage authenticates with the provider. Set it explicitly on each stage. Pass the fields of one credential mode only. Responses return only mode.
modestring(Managed)managed: Agora provides the provider authentication.
modestring(BYOK)byok: You pass your own provider credentials.
fieldsobject(BYOK)Your provider credentials, keyed by the provider's field name. Most providers take one field, api_key. Some use other names, such as key or credentials, or take more than one field, such as an AWS access key ID and secret access key. Each model page lists its provider's fields. In an agent, each value must be a $secrets.<set_name>.<key> reference to a secret set. An ephemeral session also accepts the values themselves. Agora resolves references when each session starts. The values are never returned.
[key: string]stringvendorstringThe LLM provider, for example openai.
stylestringThe API style used to communicate with the model, for example openai for OpenAI and OpenAI-compatible APIs.
modelstringThe provider model.
urlstringA custom provider endpoint. Don't also put the endpoint in params. For Google Gemini in an ephemeral session, the URL can include your API key as key=<your_api_key>, with credential.fields left out. A saved agent's url can't contain a key.
headersobjectCustom HTTP headers sent to the provider endpoint, at most 32. They are write-only and are never returned. A value can be a whole $secrets.<set>.<key> reference when the stage uses byok and an approved provider endpoint. Agora resolves it when each session starts. A header name that looks like a credential, such as X-Api-Key, must use a reference. Transport, identity, and provider authentication headers are reserved. Set provider authentication in credential.
[key: string]stringparamsobjectProvider-specific settings that aren't secret, such as reasoning_effort, passed to the provider as they are. Keep API keys in credential, not here.
input_modalitiesarray<string>The input types sent to the model, for example ["text"].
output_modalitiesarray<string>The output types requested from the model, for example ["text"].
max_historyintegerThe number of recent conversation messages the LLM keeps as context. It counts messages, not user and agent pairs. The agent's instructions don't count toward this limit.
failure_messagestringThe message the agent speaks with the TTS stage when the LLM fails to produce a response.
toolsarray<object>Function tools the model can call. An agent can have up to 32 tools in total, including tools discovered from mcp_servers. Tool names must be unique, ignoring case.
typestringAlways function.
namestringThe tool name shown to the model. It starts with a letter and contains only letters and digits, up to 64 characters. It can't start with mcp, can't be ragsearch_tool, and can't match an MCP, built-in, or model-native tool.
descriptionstringWhat the tool does, 1 to 1,024 characters. The model uses it to decide when to call the tool.
parametersobjectA JSON Schema that describes the tool's arguments.
executionobjectHow the agent runs the tool.
modestringsync: The agent waits for the tool response before it continues.
serverobjectThe HTTP endpoint the agent calls to run the tool.
methodstringThe HTTP method.
urlstringThe HTTPS URL of the endpoint, up to 2,048 characters.
headersobjectHTTP headers sent to the endpoint, up to 32. They are write-only and are never returned.
[key: string]stringbodyobjectAdditional fields to include in the request body.
timeout_msintegerThe request timeout in milliseconds.
mcp_serversarray<object>MCP servers whose tools the model can call.
namestringA name for the MCP server, 1 to 48 letters and digits.
endpointstringThe HTTPS URL of the MCP server, up to 2,048 characters.
transportstringThe MCP transport. streamable_http: Streamable HTTP.
headersobjectHTTP headers sent to the MCP server, up to 32. They are write-only and are never returned.
[key: string]stringallowed_toolsarray<string>The tools the model can call from this server:
- Omit the field, or include
*in the list, to allow every tool. - Pass an empty list to allow no tools.
- Otherwise, only the listed tools are allowed.
timeout_msintegerThe request timeout in milliseconds.
ttsobjectThe text-to-speech (TTS) stage, which converts the agent's replies to speech.
credentialManaged | BYOKHow this stage authenticates with the provider. Set it explicitly on each stage. Pass the fields of one credential mode only. Responses return only mode.
modestring(Managed)managed: Agora provides the provider authentication.
modestring(BYOK)byok: You pass your own provider credentials.
fieldsobject(BYOK)Your provider credentials, keyed by the provider's field name. Most providers take one field, api_key. Some use other names, such as key or credentials, or take more than one field, such as an AWS access key ID and secret access key. Each model page lists its provider's fields. In an agent, each value must be a $secrets.<set_name>.<key> reference to a secret set. An ephemeral session also accepts the values themselves. Agora resolves references when each session starts. The values are never returned.
[key: string]stringvendorstringThe TTS provider, for example microsoft.
urlstringA custom provider endpoint. Don't also put the endpoint in params.
headersobjectCustom HTTP headers sent to the provider endpoint, at most 32. They are write-only and are never returned. A value can be a whole $secrets.<set>.<key> reference when the stage uses byok and an approved provider endpoint. Agora resolves it when each session starts. A header name that looks like a credential, such as X-Api-Key, must use a reference. Transport, identity, and provider authentication headers are reserved. Set provider authentication in credential.
[key: string]stringparamsobjectProvider-specific settings that aren't secret, such as the voice and, where the provider requires it, the model, passed to the provider as they are. Keep API keys in credential, not here.
skip_patternsarray<string>Bracketed text that the agent doesn't speak, such as tone or action notes in the LLM output:
fullwidth_parentheses: Text in（）.lenticular_brackets: Text in【】.parentheses: Text in( ).square_brackets: Text in[ ].curly_braces: Text in{ }.
turn_detectionobjectHow the agent detects when the user starts and stops speaking, and handles interruptions.
speech_thresholdnumberThe speech detection threshold. Lower values detect speech more easily. Higher values ignore weak speech.
start_of_speechSemantic | VAD | ManualHow the agent detects that the user starts speaking. Pass the fields of one detection type only. If you omit it, the agent uses semantic detection with its defaults.
typestring(Semantic)semantic: Detects a meaningful start of speech. If you omit type, the agent uses semantic.
speaking_interrupt_duration_msinteger(Semantic)How long in milliseconds the user must speak to interrupt the agent while it's speaking.
typestring(VAD)vad: Uses voice activity detection (VAD) on the audio signal.
interrupt_duration_msinteger(VAD)Speech shorter than this, in milliseconds, is ignored.
speaking_interrupt_duration_msinteger(VAD)How long in milliseconds the user must speak to interrupt the agent while it's speaking.
prefix_padding_msinteger(VAD)How many milliseconds of audio before the detected start of speech to keep, so the beginning of the speech isn't clipped.
typestring(Manual)manual: Your client signals when the user starts speaking. This needs client signaling, which isn't available yet.
end_of_speechSemantic | VAD | ManualHow the agent detects that the user has finished speaking. Pass the fields of one detection type only. If you omit it, the agent uses semantic detection with its defaults.
typestring(Semantic)semantic: Considers whether the utterance sounds complete. If you omit type, the agent uses semantic.
silence_duration_msinteger(Semantic)The silence in milliseconds that ends the turn.
max_wait_msinteger(Semantic)The maximum time in milliseconds to wait before ending the turn, from 500 to 10,000. Set to -1 to wait without a timeout.
pause_state_enabledboolean(Semantic)Whether the agent detects a pause within an utterance, such as "hold on", and waits for more input.
typestring(VAD)vad: Uses the length of the silence after the speech.
silence_duration_msinteger(VAD)The silence in milliseconds that ends the turn.
typestring(Manual)manual: Your client signals when the user stops speaking. This needs client signaling, which isn't available yet.
interruptionStart of speech | Keywords | OffHow the user can interrupt the agent while it speaks or thinks. Pass the fields of one interruption mode only. If you omit it, any user speech interrupts the agent.
modestring(Start of speech)start_of_speech: Any user speech interrupts the agent.
modestring(Keywords)keywords: Only the phrases in keywords interrupt the agent.
keywordsarray<string>(Keywords)The phrases that interrupt the agent, 1 to 128.
modestring(Off)off: The user can't interrupt the agent.
when_offstring(Off)What happens to user speech that arrives while the agent speaks or thinks:
append: The agent responds to the speech after the current reply.ignore: The agent discards the speech.
silence_configobjectWhat the agent does after a period of silence. This only prompts the user. To hang up a phone call after silence, use call_policy.max_silence_duration_ms.
enabledbooleanWhether to act on silence.
timeout_msintegerHow long the silence lasts, in milliseconds, before the agent acts, up to 60,000. Applies only when enabled is true.
actionstringWhat the agent does when the timeout is reached:
speak: Speakscontentas written.think: Givescontentto the LLM as an instruction, and responds to it.
contentstringThe text to speak, or the instruction for the LLM, depending on action.
avatarobjectThe avatar that represents the agent on video.
enabledbooleanWhether to show the avatar.
credentialManaged | BYOKHow this stage authenticates with the provider. Set it explicitly on each stage. Pass the fields of one credential mode only. Responses return only mode.
modestring(Managed)managed: Agora provides the provider authentication.
modestring(BYOK)byok: You pass your own provider credentials.
fieldsobject(BYOK)Your provider credentials, keyed by the provider's field name. Most providers take one field, api_key. Some use other names, such as key or credentials, or take more than one field, such as an AWS access key ID and secret access key. Each model page lists its provider's fields. In an agent, each value must be a $secrets.<set_name>.<key> reference to a secret set. An ephemeral session also accepts the values themselves. Agora resolves references when each session starts. The values are never returned.
[key: string]stringvendorstringThe avatar provider. generic passes provider-neutral parameters through.
paramsobjectProvider-specific settings, passed to the provider as they are.
filler_wordsobjectShort phrases the agent says while it waits for the LLM to respond, such as when it waits for a tool call.
enablebooleanWhether to play filler words.
triggerobjectWhen to play a filler word.
modestringfixed_time: Play a filler word when the LLM hasn't responded within response_wait_ms.
response_wait_msintegerHow long in milliseconds to wait for the LLM response before playing a filler word, for example 1500.
contentStatic | GeneratedWhere the filler words come from. Pass the fields of one source only.
modestring(Static)static: Pick a phrase from phrases.
phrasesarray<string>(Static)The filler phrases, 1 to 100 non-empty strings.
selection_rulestring(Static)How the agent picks the next phrase:
shuffle: In random order.round_robin: In list order, starting over after the last phrase.
modestring(Generated)generated: Generate a phrase from instructions.
instructionsstring(Generated)The instructions used to generate filler phrases. They can't be empty or only whitespace.
fallback_strategystring(Generated)What to use when a generated phrase isn't available.
transportRTC | TelephonyHow the agent connects to the participant. Pass the fields of one transport type only.
typestring(RTC)rtc: The agent joins an RTC channel.
channelstring(RTC)The name of the RTC channel to join, 1 to 256 characters.
tokenstring(RTC)The RTC token the agent uses to join the channel. Required when the project has an App Certificate enabled. To renew it, update the session.
uidString | Integer(RTC)The user ID the agent uses in the channel. Pass a string of up to 255 characters, such as "1002" or "agent-bot", or an integer from 0 to 4294967295, such as 1002. Omit it, or pass 0, to let Agora assign a user ID that differs from subscribe_uids.
subscribe_uidsarray<String | Integer>(RTC)The user ID of the participant the agent talks to, as a string or an integer. Pass exactly one user ID.
audio_scenariostring(RTC)The audio scenario of the agent in the channel:
aiserver: Optimized for latency and network resilience in conversations with an agent.chorus: For participants with good network conditions who need ultra-low latency.
encryptionobject(RTC)Media encryption for the RTC channel. These values are never returned.
modestringThe encryption mode. Agora recommends aes_128_gcm2 or aes_256_gcm2, which use a salt.
keystringThe encryption key.
saltstringA Base64-encoded salt that is 32 bytes long after decoding. Required when mode is aes_128_gcm2 or aes_256_gcm2.
typestring(Telephony)telephony: The agent places a phone call.
fromstring(Telephony)The number_id of the number in the project to call from. Phone numbers aren't accepted. Import the number first.
tostring(Telephony)The phone number to call, in E.164 format, for example +14155550100.
call_policyobject(Telephony)Limits and behavior for outbound phone calls. Each limit you omit adds no limit.
max_ring_duration_msintegerThe maximum time in milliseconds from starting the dial until the call is answered. If the call isn't answered in time, the dial attempt ends.
max_call_duration_secondsintegerThe maximum length of the call in seconds, measured from when it's answered. The session's lifecycle limits can end the call earlier.
max_silence_duration_msintegerHang up when nobody on the call has spoken for this many milliseconds. This is separate from pipeline.silence_config, which only prompts the user.
end_callobjectConditions under which the agent can end the call itself. Every condition is off unless you set it to true.
on_user_requestbooleanEnd the call when the caller clearly says goodbye or asks to hang up.
on_voicemailbooleanEnd the call when the agent reaches voicemail, such as a "please leave a message after the tone" announcement.
on_ai_assistantbooleanEnd the call when the call is answered by an AI assistant, a voice secretary, or another automated answering system.
valuesobjectValues for the agent's variables, keyed by variable name, for this session only. Each key must be a variable the agent declares, and each value must match its type and options. Pass a value for every required variable. null values are rejected.
lifecycleobjectWhen the session ends on its own.
idle_timeout_msintegerHow long in milliseconds the session continues with no participant present: after the subscribed user leaves the RTC channel, or after the other side of a phone call hangs up. It isn't silence detection. Set to 0 to turn off the idle timer. Can't be greater than max_duration_ms.
max_duration_msintegerThe maximum length of the session in milliseconds, measured from start_ts. Defaults to 5 minutes. The maximum is 1 hour.
graceful_stopobjectHow the agent finishes when you stop the session, or when the idle timer expires. It doesn't extend max_duration_ms, and it doesn't add a farewell message.
enabledbooleanWhether the agent finishes what it's saying before it leaves.
timeout_msintegerThe longest time in milliseconds the agent can take to finish.
data_policyobjectHow Agora handles the session's data. You set it when the session starts and can't change it afterward.
retentionstringHow long Agora keeps the conversation data:
30_days: Agora keeps the data for 30 days.none: Agora doesn't keep the data, and variable extraction doesn't run. Use it, for example, when a caller declines recording.
labelsobjectKey-value labels for this session, such as a team or customer ID. They're included in the payload of notification events.
[key: string]stringResponse Body
The session was created.
Response Headers
agent_session_idstringThe ID of the session.
create_tsintegerThe time the session was created, as a Unix timestamp in seconds.
statusstringThe status of the session when it starts. For a phone call, RUNNING doesn't mean the call was answered.
Request examples
curl -X POST 'https://preview.ai.agora.io/conversational-ai/v1/projects/string/sessions/ephemeral' \ -H 'Content-Type: application/json' \ -d '{ "agent": { "instructions": "Answer account questions concisely.", "pipeline": { "mode": "cascaded", "asr": { "credential": { "mode": "managed" }, "vendor": "deepgram", "model": "nova-3", "language": "en-US" }, "llm": { "credential": { "mode": "byok", "fields": { "api_key": "$secrets.support_prod.llm" } }, "vendor": "openai", "style": "openai", "model": "<model_name>" }, "tts": { "credential": { "mode": "managed" }, "vendor": "minimax", "params": { "model": "speech-2.6-turbo", "voice_setting": { "voice_id": "English_captivating_female1", "speed": 1 } } } } }, "transport": { "type": "rtc", "channel": "support-4821", "token": "<your_rtc_token>", "uid": "1002", "subscribe_uids": [ "1001" ] }}'Response example
{ "agent_session_id": "a42al97tw77hv93ja98dm74fk56lw97x", "create_ts": 1737111452, "status": "RUNNING"}