Create an agent
Updated
Saves a reusable agent configuration in your project.
Preview documentation
https://preview.ai.agora.io/conversational-ai/v1/projects/{appid}/agentsUse this endpoint to save an agent that you can then use to start sessions and campaigns. Only agent_name is required. If you omit greeting, the agent doesn't greet participants automatically.
Saving or updating an agent doesn't change sessions that are already running.
Keep provider keys in secrets
Set credential on each pipeline stage. With byok, pass your provider keys in credential.fields as $secrets.<set>.<key> references to a secret set. Most providers take one field, api_key. Agora checks that each reference exists when you create the agent. Keep credentials out of params.
appidstringThe App ID of your project.
agent_namestringA name for the agent, 1 to 255 characters. It doesn't need to be unique.
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.
Response Body
The agent was created. The response body contains the saved agent.
Response Headers
agent_idstringThe ID of the agent, a UUID.
agent_namestringA name for the agent, 1 to 255 characters. It doesn't need to be unique.
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.
vendorstringThe 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.
vendorstringThe 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.
paramsobjectProvider-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.
bodyobjectAdditional 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.
allowed_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.
vendorstringThe TTS provider, for example microsoft.
modelstringThe TTS model the agent uses. Returned in responses only.
urlstringA custom provider endpoint. Don't also put the endpoint in params.
paramsobjectProvider-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.
vendorstringThe 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.
create_tsintegerThe time the agent was created, as a Unix timestamp in seconds.
update_tsintegerThe time the agent was last updated, as a Unix timestamp in seconds.
Request examples
curl -X POST 'https://preview.ai.agora.io/conversational-ai/v1/projects/string/agents' \ -H 'Content-Type: application/json' \ -d '{ "agent_name": "Customer Support Agent", "instructions": "You are a support agent for Acme. Address the caller as {{customer_name}}. Be concise.", "variables": { "customer_name": { "type": "str", "required": true }, "resolution_status": { "type": "str", "options": [ "resolved", "follow_up", "unresolved" ], "extract": true, "description": "Outcome of the conversation." } }, "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>", "max_history": 12, "failure_message": "I'\''m sorry, I couldn'\''t generate a response. Please try again." }, "tts": { "credential": { "mode": "managed" }, "vendor": "minimax", "params": { "model": "speech-2.6-turbo", "voice_setting": { "voice_id": "English_captivating_female1", "speed": 1 } } }, "silence_config": { "enabled": true, "timeout_ms": 3000, "action": "speak", "content": "Hello, how can I help you?" } }, "greeting": { "mode": "text", "on": "each_join", "delay_ms": 0, "text": "Hi, thanks for calling Acme." }}'Response example
{ "agent_id": "3f6c2a9e-8d1b-4e7a-9c55-0b2f7d1e4a10", "agent_name": "Customer Support Agent", "instructions": "You are a support agent for Acme. Address the caller as {{customer_name}}. Be concise.", "variables": { "customer_name": { "type": "str", "required": true }, "resolution_status": { "type": "str", "options": [ "resolved", "follow_up", "unresolved" ], "extract": true, "description": "Outcome of the conversation." } }, "pipeline": { "mode": "cascaded", "asr": { "credential": { "mode": "managed" }, "vendor": "deepgram", "model": "nova-3", "language": "en-US" }, "llm": { "credential": { "mode": "byok" }, "vendor": "openai", "style": "openai", "model": "<model_name>", "max_history": 12, "failure_message": "I'm sorry, I couldn't generate a response. Please try again." }, "tts": { "credential": { "mode": "managed" }, "vendor": "minimax", "params": { "model": "speech-2.6-turbo", "voice_setting": { "voice_id": "English_captivating_female1", "speed": 1 } } }, "silence_config": { "enabled": true, "timeout_ms": 3000, "action": "speak", "content": "Hello, how can I help you?" } }, "greeting": { "mode": "text", "on": "each_join", "delay_ms": 0, "text": "Hi, thanks for calling Acme." }, "create_ts": 1786543331, "update_ts": 1786543331}