Create Agent

POST

/api/v1/indices/rag/app/create

cURL

curl -X POST "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/app/create" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Customer Service Q&A Assistant",
    "agent_desc": "Intelligent customer service Q&A agent based on product documentation",
    "agent_scene": "chat",
    "agent_config": {
        "agent_policy": "agentic",
        "agent_model": "qwen3.7-plus",
        "enable_session_file": "false",
        "enable_refusal": "true",
        "enable_anti_leak": "false",
        "enable_rich_text": "false",
        "enable_citation": "true",
        "temperature": 0.5,
        "kb_search_configs": [
            {
                "id": "pipeline-xxxxxx",
                "weight": 1,
                "credibility_level": "high",
                "dense_similarity_top_k": 10,
                "rerank_top_n": 5,
                "rerank_min_score": 0.3,
                "rerank": {
                    "model_name": "gte-rerank-hybrid",
                    "rerank_mode": "qa"
                }
            }
        ]
    }
}'

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status_code": 200,
  "code": "Success",
  "message": "",
  "status": "SUCCESS",
  "success": true,
  "data": {
    "agent_id": "aid-8f3a1b2c4d5e6f70",
    "agent_name": "Customer Service Q&A Assistant",
    "agent_version": "beta",
    "agent_status": "draft"
  }
}

Create a new RAG Agent with initial status draft and version beta.

Creating an Agent requires Knowledge Base - Create permission.

agent_config structure

The field composition of agent_config depends on the value of agent_scene:

Chat: agent_policy, agent_model, enable_session_file, enable_refusal, enable_anti_leak, enable_rich_text, enable_citation, temperature, max_num_llm_calls, max_completion_tokens, session_file_max_parse_length, kb_search_configs
Search: agent_policy, enable_kb_router, kb_router_model, rerank_top_n, kb_search_configs, hybrid_rerank

kb_search_configs[] element fields: id, weight, credibility_level, dense_similarity_top_k, sparse_similarity_top_k, rerank_top_n, rerank_min_score, rerank, search_filters

Fields such as name, desc, and knowledge_type are auto-filled by the system from the Knowledge Base and will be overridden even if passed in.

Authorizations

string

header

required

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

Body

application/json

string

required

Agent name, up to 200 characters, must be unique within the same tenant and scene.

Required range:length <= 200

enum<string>

required

Agent scene: chat (knowledge Q&A) or search (knowledge retrieval).

Available options:chat,search

string

Agent description, up to 1000 characters.

Required range:length <= 1000

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

ID of the created Agent.

string

Agent name.

string

Agent version number. beta for newly created agents.

string

Agent status. draft for newly created agents.

​agent_config structure

Authorizations

Body

Response

agent_config structure