# 更新智能体配置 (/zh-CN/api-reference/api-ref/conversational-ai/update)

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

更新指定运行中智能体的部分参数配置。

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

## Servers

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

## Authorization

This endpoint requires authentication.

- `Basic Auth`
- `Agora Token`

## Parameters

- `Authorization` (header, required, string) - 发送 HTTP 请求时，你可以从以下鉴权方式中任选其一：

1. **使用 Token 认证（推荐）**：参考[实现 HTTP 鉴权](/zh-CN/ai/build/http-basic-auth#使用-token-认证)生成 Token 并填入 `Authorization` Header。传参示例：`Authorization: agora token="007abcxxxxxxx123"`。
2. **使用 Basic Auth**：参考[实现 HTTP 鉴权](/zh-CN/ai/build/http-basic-auth#使用-http-基本认证)生成 Base64 编码的 `Authorization` 字段。传参示例：`Authorization: Basic NDI1OTQ3N2I4MzYy...YwZjA=`。

  - Example: `agora token="007abcxxxxxxx123"`
- `appid` (path, required, string) - 你的项目使用的 [App ID](/zh-CN/ai/get-started/enable-service#%E8%8E%B7%E5%8F%96-app-id)。
- `agentId` (path, required, string) - 智能体实例 ID，即智能体的唯一标识。调用 [POST 创建对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/join) 成功后在响应包体中获取。

## Request body

- `properties` (object)
  - `properties.token` (string) - 用于鉴权的动态密钥。如果你的项目已启用 App 证书，则务必在该字段中传入你项目的动态密钥。运行中的智能体收到 `104 agent expire` 事件后，你可以调用本接口并更新该字段以刷新 RTC Token。详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。
  - `properties.llm` (object) - 大语言模型 (LLM) 设置。
    - `properties.llm.system_messages` (array) - 一组每次调用 LLM 时被附加在最前的预定义信息，用于控制 LLM 输出。可以是角色设定、提示词和回答样例等。要求与 OpenAI 协议兼容。
      - `properties.llm.system_messages.items` (object)
    - `properties.llm.params` (object) - 在消息体内传输的 LLM 附加信息，例如使用的模型、最大 Token 数限制等。不同的 LLM 供应商支持的配置不同，请参考对应文档按需填入。
> [!CAUTION]
> 该字段更新后将覆盖智能体创建时的配置。更新时，请确保传入完整的 `params` 字段。

### Request body example

```json
{
  "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
      }
    }
  }
}
```

## Responses

### 200

- 若返回的状态码为 `200` 则表示请求成功。响应包体中包含本次请求的结果。
- 若返回的状态码不为 `200` 则表示请求失败。响应包体中包含错误的类别和描述，你可以参考[响应状态码](/zh-CN/api-reference/conversational-ai/rest-api/api/response-code)了解可能的原因。

- `agent_id` (string) - 智能体唯一标识符。
- `create_ts` (integer) - 智能体创建时间戳。
- `state` (string) - 智能体运行状态：
- `IDLE` (0)：空闲状态的智能体。
- `STARTING` (1)：正在启动的智能体。
- `RUNNING` (2)：正在运行的智能体。
- `STOPPING` (3)：正在停止的智能体。
- `STOPPED` (4)：已完成退出的智能体。
- `FAILED` (6)：执行失败的智能体。

## Response examples

### 200

```json
{
  "agent_id": "1NT29XOXFT4Jxxxx410TXRCFG10HI00",
  "create_ts": 173836896,
  "state": "RUNNING"
}
```