Skip to main content

Create Agent

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

Prerequisites

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

Endpoint

POST /api/v1/indices/rag/app/create Create a new RAG Agent. An Agent is the encapsulated entity of the knowledge Q&A / retrieval capability, containing model configuration, retrieval strategy, security policy, and more. After creation, the Agent is in the draft state with version number beta. You can modify the configuration via the Update Agent API and publish it via the Deploy Agent API. The agent_name must be unique within the same tenant and scene.

agent_config structure

The field composition of agent_config depends on the value of agent_scene:
  • chat scene: 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 scene: 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 automatically filled by the system from the knowledge base; values passed in are ignored and overwritten.

Request body

FieldRequiredTypeDescription
agent_nameYesstringAgent name, up to 200 characters, must be unique within the same tenant and scene.
agent_descNostringAgent description, up to 1000 characters.
agent_sceneYesstringAgent scene: chat (knowledge Q&A) or search (knowledge retrieval).
agent_configNoobjectAgent configuration. If not provided, default configuration is used. See the sub-field table below.
agent_config sub-fields
FieldRequiredTypeDescription
agent_modelNostringModel name used by the agent, e.g. qwen3.7-plus, qwen3.6-plus.
agent_policyNostringAgent policy, e.g. agentic.
enable_anti_leakNostringWhether to enable the anti-leak feature, true or false.
enable_citationNostringWhether to enable citation annotations, true or false.
enable_kb_routerNostringWhether to enable knowledge base routing (search scene). true or false.
enable_refusalNostringWhether to enable the refusal feature, true or false.
enable_rich_textNostringWhether to enable rich text output, true or false.
enable_session_fileNostringWhether to enable the session file feature, true or false.
hybrid_rerankNoobjectGlobal fusion rerank config (search scene). See the sub-field table below.
kb_router_modelNostringRouter model name. Required when enable_kb_router is true. Must be in the platform whitelist.
kb_search_configsNoarray<object>List of knowledge base retrieval configurations. See the element table below.
max_completion_tokensNointegerMaximum generation tokens. Must be >= 1.
max_num_llm_callsNointegerMaximum number of LLM calls for the agent.
rerank_top_nNointegerFusion rerank Top N (search scene). Range [1, 20].
session_file_max_parse_lengthNointegerMaximum parsing length for session files. Must be less than the model's max_context_length.
temperatureNonumberModel sampling temperature, range [0, 2].
user_system_promptNostringCustom 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
FieldRequiredTypeDescription
credibility_levelNostringKnowledge base credibility level, e.g. high, medium, low.
dense_similarity_top_kNointegerTop-K quantity returned by dense retrieval.
idNostringAssociated knowledge base Pipeline ID.
rerankNoobjectReranking configuration. See the sub-field table below.
rerank_min_scoreNonumberMinimum rerank score threshold. Chunks with a score below this value are filtered out.
rerank_top_nNointegerTop-N quantity retained after reranking.
search_filtersNoarrayRetrieval filter conditions, validated against the knowledge base schema.
sparse_similarity_top_kNointegerSparse retrieval Top K. Range [1, 100].
weightNonumberKnowledge base weight.
kb_search_configs[].rerank sub-fields
FieldRequiredTypeDescription
model_nameNostringReranking model name, e.g. gte-rerank-hybrid.
rerank_instructNostringCustom rerank instruction, only effective when rerank_mode is custom. Max 500 characters.
rerank_modeNostringRerank 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
FieldRequiredTypeDescription
model_nameNostringFusion rerank model code. For VL knowledge bases, only multimodal models are supported; otherwise all rerank models are supported.
rerank_modeNostringFusion rerank mode: qa, similar, or custom. rerank_instruct is automatically cleared when not in custom mode.
rerank_instructNostringCustom 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/create" \
  -H "Authorization: Bearer $BAILIAN_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"
                }
            }
        ]
    }
}'
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": "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"
  }
}

Response fields

FieldTypeDescription
request_idstringUnique request identifier. Provide this ID when troubleshooting issues.
status_codeintegerHTTP status code.
codestringResponse code. Success on success.
messagestringInformational message.
statusstringRequest status: SUCCESS or FAILED.
successbooleanWhether the request succeeded.
data.agent_idstringID of the created Agent.
data.agent_namestringAgent name.
data.agent_versionstringAgent version number. beta for newly created agents.
data.agent_statusstringAgent status. draft for newly created agents.

Error codes

HTTP status codeError codeDescription
400Index.InvalidParameterInvalid 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
}
Managed Agent API
Flow Agent API
Sandbox API
RAG API
Long-term Memory
ParseX API
Security API
Framework Integration
Application components
More
Assistant API (Deprecated)