Update Agent

Prerequisites

Obtain an Alibaba Cloud Model Studio API Key and workspace ID first. For authentication, see API Authentication. Updating an Agent requires the Knowledge Base - Modify permission, which is determined by the user's role in Workspace Member Management. See Permissions.

Endpoint

POST /api/v1/indices/rag/app/update Update the name, description, version description, or configuration of a specified Agent. Only the beta version allows modifying agent_config; when a published version number is passed, only agent_version_desc can be modified.

agent_config can only be modified on the beta draft version; published versions can only modify the agent_version_desc field. To modify a published version's config, first call the update endpoint to update the beta draft, then call the deploy endpoint to publish a new version.

Request body

Field	Required	Type	Description
`agent_id`	Yes	string	Agent ID.
`agent_name`	No	string	New Agent name, up to 200 characters.
`agent_desc`	No	string	New Agent description, up to 1000 characters.
`agent_version`	No	string	Agent version number, defaults to `beta`. When a published version number is passed, only `agent_version_desc` can be modified.
`agent_version_desc`	No	string	Version description.
`agent_config`	No	object	New Agent configuration (only the beta version allows modification), with the same structure as the agent_config in the create API. See the sub-field table below.

The agent_config structure is the same as in Create Agent.

agent_config sub-fields

Field	Required	Type	Description
`agent_model`	No	string	Model name used by the agent, e.g. `qwen3.7-plus`, `qwen3.6-plus`.
`agent_policy`	No	string	Agent policy, e.g. `agentic`.
`enable_anti_leak`	No	string	Whether to enable the anti-leak feature, `true` or `false`.
`enable_citation`	No	string	Whether to enable citation annotations, `true` or `false`.
`enable_kb_router`	No	string	Whether to enable knowledge base routing (search scene). `true` or `false`.
`enable_refusal`	No	string	Whether to enable the refusal feature, `true` or `false`.
`enable_rich_text`	No	string	Whether to enable rich text output, `true` or `false`.
`enable_session_file`	No	string	Whether to enable the session file feature, `true` or `false`.
`hybrid_rerank`	No	object	Global fusion rerank config (search scene). See the sub-field table below.
`kb_router_model`	No	string	Router model name. Required when `enable_kb_router` is `true`. Must be in the platform whitelist.
`kb_search_configs`	No	array<object>	List of knowledge base retrieval configurations. See the element table below.
`max_completion_tokens`	No	integer	Maximum generation tokens. Must be >= 1.
`max_num_llm_calls`	No	integer	Maximum number of LLM calls for the agent.
`rerank_top_n`	No	integer	Fusion rerank Top N (search scene). Range [1, 20].
`session_file_max_parse_length`	No	integer	Maximum parsing length for session files. Must be less than the model's max_context_length.
`temperature`	No	number	Model sampling temperature, range [0, 2].
`user_system_prompt`	No	string	Custom system prompt for the chat scene. Place it at the top level of agent_config; it is passed through without validation, and its length and effect are determined by the downstream runtime. Note the field name is user_system_prompt, not system_prompt.

agent_config.kb_search_configs[] elements

Field	Required	Type	Description
`credibility_level`	No	string	Knowledge base credibility level, e.g. `high`, `medium`, `low`.
`dense_similarity_top_k`	No	integer	Top-K quantity returned by dense retrieval.
`id`	No	string	Associated knowledge base Pipeline ID.
`rerank`	No	object	Reranking configuration. See the sub-field table below.
`rerank_min_score`	No	number	Minimum rerank score threshold. Chunks with a score below this value are filtered out.
`rerank_top_n`	No	integer	Top-N quantity retained after reranking.
`search_filters`	No	array	Retrieval filter conditions, validated against the knowledge base schema.
`sparse_similarity_top_k`	No	integer	Sparse retrieval Top K. Range [1, 100].
`weight`	No	number	Knowledge base weight.

kb_search_configs[].rerank sub-fields

Field	Required	Type	Description
`model_name`	No	string	Reranking model name, e.g. `gte-rerank-hybrid`.
`rerank_instruct`	No	string	Custom rerank instruction, only effective when `rerank_mode` is `custom`. Max 500 characters.
`rerank_mode`	No	string	Rerank mode: `qa` (question answering), `similar` (similarity), or `custom` (custom instruction). `rerank_instruct` is automatically cleared when not in `custom` mode.

agent_config.hybrid_rerank sub-fields

Field	Required	Type	Description
`model_name`	No	string	Fusion rerank model code. For VL knowledge bases, only multimodal models are supported; otherwise all rerank models are supported.
`rerank_mode`	No	string	Fusion rerank mode: `qa`, `similar`, or `custom`. `rerank_instruct` is automatically cleared when not in `custom` mode.
`rerank_instruct`	No	string	Custom fusion rerank instruction, only effective when `rerank_mode` is `custom`. Max 500 characters.

Request example

curl -X POST "$BASE_URL/api/v1/indices/rag/app/update" \
  -H "Authorization: Bearer $BAILIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "aid-8f3a1b2c4d5e6f70",
    "agent_name": "Customer Service Q&A Assistant v2",
    "agent_config": {
        "agent_policy": "agentic",
        "agent_model": "qwen3.6-plus",
        "enable_session_file": "false",
        "enable_refusal": "true",
        "enable_anti_leak": "true",
        "enable_rich_text": "false",
        "enable_citation": "true",
        "temperature": 0.7,
        "max_num_llm_calls": 10,
        "kb_search_configs": [
            {
                "id": "pipeline-xxxxxx",
                "weight": 1,
                "dense_similarity_top_k": 15,
                "rerank_top_n": 5,
                "rerank": {
                    "model_name": "gte-rerank-hybrid",
                    "rerank_mode": "custom",
                    "rerank_instruct": "Rank documents by relevance according to the technical domain of the user's question"
                }
            }
        ]
    }
}'

BASE_URL is https://{workspace_id}.cn-beijing.maas.aliyuncs.com ({workspace_id} is the workspace ID), and BAILIAN_API_KEY is your Alibaba Cloud Model Studio API Key.

Response example

Returns 200 on success.

{
  "request_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "status_code": 200,
  "code": "Success",
  "message": "",
  "status": "SUCCESS",
  "success": true,
  "data": {
    "agent_id": "aid-8f3a1b2c4d5e6f70"
  }
}

Response fields

Field	Type	Description
`request_id`	string	Unique request identifier. Provide this ID when troubleshooting issues.
`status_code`	integer	HTTP status code.
`code`	string	Response code. `Success` on success.
`message`	string	Informational message.
`status`	string	Request status: `SUCCESS` or `FAILED`.
`success`	boolean	Whether the request succeeded.
`data.agent_id`	string	Agent ID.

Error codes

HTTP status code	Error code	Description
400	`Index.InvalidParameter`	Invalid request parameters. Please check that all parameters are complete and correctly typed.

Error response example:

{
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status_code": 400,
  "code": "Index.InvalidParameter",
  "message": "Invalid request parameters. Please check that all parameters are complete and correctly typed.",
  "status": "FAILED",
  "success": false
}

​Prerequisites

​Endpoint

​Request body

​Request example

​Response example

​Response fields

​Error codes

Prerequisites

Endpoint

Request body

Request example

Response example

Response fields

Error codes