Update agent configuration

POST

https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/update

Use this endpoint to adjust Conversational AI agent instance parameters at runtime.

Request

Path parameters

appid stringrequired

The App ID of the project.

agentId stringrequired

The agent instance ID you obtained after successfully calling join to Start a conversational AI agent.

Request body

APPLICATION/JSON

BODY

properties objectnullable
Show propertiesHide properties
- token stringnullable
  The authentication token used by the agent to join the channel.
- llm objectnullable
  Large Language Model (LLM) settings.
  Show propertiesHide properties
  system_messages array[object]nullable
  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.
  params objectnullable
  Additional 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.
  info
  Updating this field overwrites the configuration set when the agent was created. When updating, make sure to pass the complete params field.

Response

If the returned status code is 200, the request was successful. The response body contains the result of the request.
OK
- agent_id string
  Unique id of the agent instance
- create_ts integer
  Timestamp of when the agent was created
- status string
  Possible values: IDLE, STARTING, RUNNING, STOPPING, STOPPED, RECOVERING, FAILED
  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.
  
  RECOVERING (5): The agent is recovering.
  
  FAILED (6): The agent failed to execute.
If the returned status code is not 200, the request failed. The response body includes the detail and reason for failure. Refer to status codes to understand the possible reasons for failure.

Authorization

This endpoint requires Basic Auth.

Request example

curl
Python
Node.js

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"
}

Update agent configuration

Request​

Path parameters​

Request body​

Response​