Update agent configuration
Updated
Updates runtime parameters of a Conversational AI agent instance.
https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/updateUse this endpoint to adjust Conversational AI agent instance parameters at runtime.
Path Parameters
appidstringThe App ID of the project.
agentIdstringThe agent instance ID you obtained after successfully calling join to Start a conversational AI agent.
Request Body
application/json
propertiesobjecttokenstringThe dynamic key used by the agent to join the RTC channel. If your project has App Certificate enabled, you must provide a valid token. When the agent receives a 104 agent expire event, call this endpoint with a new token to refresh it before it expires.
llmobjectLarge Language Model (LLM) settings.
system_messagesarray<object>A set of predefined messages appended to the beginning of each LLM request. These messages help control the LLM’s output and can include role definitions, prompts, response examples, and more. This field must be compatible with the OpenAI protocol.
paramsobjectAdditional LLM information included in the message body, such as the model used, the maximum number of tokens, and more. Supported configurations vary by LLM provider. Refer to the provider’s documentation for details.
Note
Updating this field overwrites the configuration set when the agent was
created. When updating, make sure to pass the complete params field.
mllmobjectMultimodal Large Language Model (MLLM) configuration for real-time audio and text processing.
paramsobjectAdditional MLLM configuration parameters.
For vendor-specific parameters, see the corresponding MLLM provider page listed in mllm.vendor.
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.
Response Body
The request was successful. The response body contains the result of the request.
agent_idstringUnique id of the agent instance
create_tsintegerTimestamp of when the agent was created
statusstringCurrent 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.
Request examples
curl --request post \ --url https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/update \ --header 'Authorization: Basic <credentials>' \ --data ' { "properties": { "token": "007eJxTYxxxxxxxxxxIaHMLAAAA0ex66", "llm": { "system_messages": [ { "role": "system", "content": "You are a helpful assistant. xxx" }, { "role": "system", "content": "Previously, user has talked about their favorite hobbies with some key topics: xxx" } ], "params": { "model": "abab6.5s-chat", "max_token": 1024 } } } }'Response example
{ "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB", "create_ts": 1737123456, "status": "RUNNING"}