Retrieve an agent
Updated
Retrieves the configuration of a saved agent.
Preview documentation
https://preview.ai.agora.io/conversational-ai/v1/projects/{appid}/agents/{agent_id}The response includes the agent's current ETag. Pass it in the If-Match header when you update the agent. Pipeline stages report only credential.mode. API keys and secret references are never returned.
appidstringThe App ID of your project.
agent_idstringThe ID of the agent, returned in agent_id when you create the agent.
Response Body
The request was successful. The response body contains the 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 GET 'https://preview.ai.agora.io/conversational-ai/v1/projects/string/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08'Response example
{ "agent_id": "3f6c2a9e-8d1b-4e7a-9c55-0b2f7d1e4a10", "agent_name": "Customer Support Agent", "instructions": "You are a support agent for Acme. Be concise.", "pipeline": { "mode": "cascaded", "llm": { "credential": { "mode": "byok" }, "vendor": "openai", "style": "openai", "model": "<model_name>" } }, "create_ts": 1786543331, "update_ts": 1787733713}