# Update agent configuration (/en/api-reference/api-ref/conversational-ai/update)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Updates runtime parameters of a Conversational AI agent instance.

- OpenAPI: /openapi/conversational-ai/rest-api.en.yaml
- Operation ID: agent-update
- Method: POST
- Path: /v2/projects/{appid}/agents/{agentId}/update
- Endpoint: https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/update

## Servers

- https://api.agora.io/api/conversational-ai-agent

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


## Authorization

This endpoint requires authentication.

- `tokenAuth`
- `basicAuth`

## Parameters

- `appid` (path, required, string) - The App ID of the project.
- `agentId` (path, required, string) - The agent instance ID you obtained after successfully calling `join` to [Start a conversational AI agent](/en/api-reference/api-ref/conversational-ai/join).

## Request body

- `properties` (object)
  - `properties.token` (string) - The 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`](/en/ai/reference/event-types#104-agent-expire) event, call this endpoint with a new token to refresh it before it expires.
  - `properties.llm` (object) - Large Language Model (LLM) settings.
    - `properties.llm.system_messages` (array) - 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.
      - `properties.llm.system_messages.items` (object)
    - `properties.llm.params` (object) - 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[Note]
      Updating this field overwrites the configuration set when the agent was
      created. When updating, make sure to pass the complete `params` field.
      :::
  - `properties.mllm` (object) - Multimodal Large Language Model (MLLM) configuration for real-time audio and text processing.
    - `properties.mllm.params` (object) - Additional MLLM configuration parameters.
For vendor-specific parameters, see the corresponding MLLM provider page listed in `mllm.vendor`.

## Request examples

### curl

```bash
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
            }
          }
        }
      }'
```

### Python

```python
import requests
    import json

    url = "https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/update"
    headers = {
      "Authorization": "Basic <credentials>",
      "Content-Type": "application/json"
    }

    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 = requests.post(url, headers=headers, json=data)
    print(response.status_code)
    print(response.json())
```

### Node.js

```javascript
const fetch = require('node-fetch');

    const url = 'https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/update';

    const headers = {
      'Authorization': 'Basic <credentials>',
      'Content-Type': 'application/json'
    };

    const 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
              }
          }
      }
    };

    fetch(url, {
      method: 'POST',
      headers: headers,
      body: JSON.stringify(data)
    })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));
```


### 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 the `detail` and `reason` for failure. Refer to [status codes](/en/api-reference/api-ref/conversational-ai/status-codes) to understand the possible reasons for failure.


## Responses

### 200

The request was successful. The response body contains the result of the request.

- `agent_id` (string) - Unique id of the agent instance
- `create_ts` (integer) - Timestamp of when the agent was created
- `status` (string) - 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.
  - Allowed: `IDLE` | `STARTING` | `RUNNING` | `STOPPING` | `STOPPED` | `FAILED`
### default

The request failed. The response body includes the error details.

- `detail` (string) - Detailed error information.
- `reason` (string) - The reason for the failure.

## Response examples

### 200

```json
{
  "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
  "create_ts": 1737123456,
  "status": "RUNNING"
}
```