Start a conversational AI agent
Updated
Creates and starts a Conversational AI agent instance.
https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/joinUse this endpoint to create and start a Conversational AI agent instance.
Path Parameters
The App ID of the project.
Request Body
application/json
The unique identifier of the agent. The same identifier cannot be used repeatedly.
Deprecated. Use credential_mode: "managed" within the asr, llm, or tts block instead. See Use managed mode.
A comma-separated string of one or more presets. Each preset provides a predefined configuration for ASR, LLM, and TTS. You can specify a preset for any or all of ASR, LLM, and TTS. When a preset is specified, you do not need to provide the endpoint URL, API key, or model for the preset providers. Use the asr, llm, and tts fields to configure additional settings.
The unique ID of a published agent in Conversational AI Studio. When provided, the saved agent configuration is used as the base configuration. Any fields specified in properties override the corresponding agent settings. When you specify a pipeline_id, the asr, tts, and llm fields in properties are optional.
The unique ID of a published agent in STUDIO. When provided, the saved agent configuration is used as the base configuration. Any fields specified in properties override the corresponding agent settings. When you specify a pipeline_id, the asr, tts, and llm fields in properties are optional.
Configuration details of the agent.
Response
-
If the returned status code is
200, the request was successful. The response body contains the result of the request. -
If the returned status code is not
200, the request failed. The response body includes thedetailandreasonfor failure. Refer to status codes to understand the possible reasons for failure. -
The following turn detection configuration is deprecated. To create more natural conversations and reduce unintended interruptions, Agora recommends using the latest version of
turn_detectionabove.
Response Body
application/json
application/json
Response schema
200application/jsonThe request was successful. The response body contains the result of the request.
Unique id of the agent instance
Timestamp of when the agent was created
Current status.
-
IDLE(0): Agent is idle. -
STARTING(1): The agent is being started. -
RUNNING(2): The agent is running. -
STOPPING(3): The agent is stopping. -
STOPPED(4): The agent has exited. -
FAILED(6): The agent failed to execute.
IDLE | STARTING | RUNNING | STOPPING | STOPPED | FAILEDRequest examples
curl --request post \--url https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/join \--header 'Authorization: Basic <your_base64_encoded_credentials>' \--data '{ "name": "unique_name", "properties": { "channel": "channel_name", "token": "token", "agent_rtc_uid": "1001", "remote_rtc_uids": [ "1002" ], "idle_timeout": 120, "llm": { "url": "https://api.openai.com/v1/chat/completions", "api_key": "<your_llm_key>", "system_messages": [ { "role": "system", "content": "You are a helpful chatbot." } ], "max_history": 32, "greeting_message": "Hello, how can I assist you today?", "failure_message": "Please hold on a second.", "params": { "model": "gpt-4o-mini" } }, "tts": { "vendor": "microsoft", "params": { "key": "<your_tts_api_key>", "region": "eastus", "voice_name": "en-US-AndrewMultilingualNeural" } }, "asr": { "language": "en-US" } }}'Response example
{ "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB", "create_ts": 1737111452, "status": "RUNNING"}{ "detail": "string", "reason": "string"}