Update Agent

Update the Agent name, description, or draft config.

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.

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.

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
}