Update Agent

POST

/api/v1/indices/rag/app/update

cURL

curl -X POST "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/app/update" \
  -H "Authorization: Bearer $DASHSCOPE_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"
                }
            }
        ]
    }
}'

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

Update the Agent's name, description, or draft config.

Updating an Agent requires Knowledge Base - Modify permission.

agent_config can only modify 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.

The agent_config structure is the same as Create Agent.

Authorizations

string

header

required

DashScope API Key, obtained from the API Key page in the console.

Body

application/json

string

required

Agent ID.

string

New Agent name, up to 200 characters.

Required range:length <= 200

string

New Agent description, up to 1000 characters.

Required range:length <= 1000

string

Agent version number, defaults to beta. When a published version number is passed, only agent_version_desc can be modified.

string

Version description.

object

Agent configuration object. If not provided, default configuration is used.

Show child attributes

string

Model name used by the agent, e.g. qwen3.7-plus, qwen3.6-plus.

string

Agent policy, e.g. agentic.

string

Whether to enable the anti-leak feature, true or false.

string

Whether to enable citation annotations, true or false.

string

Whether to enable knowledge base routing (search scene). true or false.

string

Whether to enable the refusal feature, true or false.

string

Whether to enable rich text output, true or false.

string

Whether to enable the session file feature, true or false.

object

Global fusion rerank config (search scene).

Show child attributes

string

Fusion rerank model code. For VL knowledge bases, only multimodal models are supported; otherwise all rerank models are supported.

string

Fusion rerank mode: qa, similar, or custom. rerank_instruct is automatically cleared when not in custom mode.

string

Custom fusion rerank instruction, only effective when rerank_mode is custom. Max 500 characters.

Required range:length <= 500

string

Router model name. Required when enable_kb_router is true. Must be in the platform whitelist.

object[]

List of knowledge base retrieval configurations.

Show child attributes

string

Knowledge base credibility level, e.g. high, medium, low.

integer

Top-K quantity returned by dense retrieval.

string

Associated knowledge base Pipeline ID.

object

Reranking configuration.

Show child attributes

string

Reranking model name, e.g. gte-rerank-hybrid.

string

Custom rerank instruction, only effective when rerank_mode is custom. Max 500 characters.

string

Rerank mode: qa (question answering), similar (similarity), or custom (custom instruction). rerank_instruct is automatically cleared when not in custom mode.

number

Minimum rerank score threshold. Chunks with a score below this value are filtered out.

integer

Top-N quantity retained after reranking.

unknown[]

Retrieval filter conditions, validated against the knowledge base schema.

integer

Sparse retrieval Top K. Range [1, 100].

Required range:1 <= x <= 100

number

Knowledge base weight.

integer

Maximum generation tokens. Must be >= 1.

Required range:x >= 1

integer

Maximum number of LLM calls for the agent.

integer

Fusion rerank Top N (search scene). Range [1, 20].

Required range:1 <= x <= 20

integer

Maximum parsing length for session files. Must be less than the model's max_context_length.

Required range:x >= 1

number

Model sampling temperature, range [0, 2].

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.

Response

200-application/json

string

Unique request identifier. Provide this ID when troubleshooting issues.

integer

HTTP status code.

string

Response code. Success on success.

string

Informational message.

enum<string>

Request status: SUCCESS or FAILED.

Available options:SUCCESS,FAILED

boolean

Whether the request succeeded.

object

Show child attributes

string

Agent ID.