Get Agent

Prerequisites

Obtain an Alibaba Cloud Model Studio API Key and workspace ID first. For authentication, see API Authentication. This is a read operation and requires only an API Key.

Endpoint

POST /api/v1/indices/rag/app/get Query the detailed information of a specified Agent, including name, description, scene, status, and configuration details for each version. You can specify a version number via agent_version to query a specific version; if not provided, all versions are returned.

Passing "release" as agent_version is not supported.

Request body

Field	Required	Type	Description
`agent_id`	Yes	string	Agent ID.
`agent_version`	No	string	Specify a version number (`beta` or a number such as `1`). If not provided, all version information is returned.

Request example

curl -X POST "$BASE_URL/api/v1/indices/rag/app/get" \
  -H "Authorization: Bearer $BAILIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "aid-8f3a1b2c4d5e6f70",
    "agent_version": "beta"
}'

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": "f6a7b8c9-d0e1-2345-fabc-456789012345",
  "status_code": 200,
  "code": "Success",
  "message": "",
  "status": "SUCCESS",
  "success": true,
  "data": {
    "agent_id": "aid-8f3a1b2c4d5e6f70",
    "agent_name": "Customer Service Q&A Assistant",
    "agent_desc": "Intelligent customer service Q&A agent based on product documentation",
    "agent_scene": "chat",
    "agent_status": "deployed",
    "create_time": "2026-07-10T14:30:00",
    "modify_time": "2026-07-15T09:15:00",
    "agent_details": [
      {
        "agent_version": "beta",
        "agent_version_desc": "Draft version",
        "publish_time": null,
        "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"
              }
            }
          ]
        }
      }
    ]
  }
}

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.
`data.agent_name`	string	Agent name.
`data.agent_desc`	string	Agent description.
`data.agent_scene`	string	Agent scene: `chat` or `search`.
`data.agent_status`	string	Agent status.
`data.create_time`	string	Creation time (ISO 8601).
`data.modify_time`	string	Modification time (ISO 8601).
`data.agent_details`	array<object>	List of Agent version details. Returns all versions when agent_version is not specified. See the element table below.

data.agent_details[] elements

Field	Type	Description
`agent_version`	string	Version number, `beta` or a number (e.g. `1`, `2`).
`agent_version_desc`	string	Version description.
`publish_time`	string	Publish time (ISO 8601). Not present for the beta version.
`agent_config`	object	Agent configuration. See the sub-field table below.
`publish_user`	string	User who published the version.

agent_config sub-fields

Field	Type	Description
`agent_model`	string	Model name used by the agent, e.g. `qwen3.7-plus`, `qwen3.6-plus`.
`agent_policy`	string	Agent policy, e.g. `agentic`.
`enable_anti_leak`	boolean	Whether to enable the anti-leak feature, `true` or `false`.
`enable_citation`	boolean	Whether to enable citation annotations, `true` or `false`.
`enable_refusal`	boolean	Whether to enable the refusal feature, `true` or `false`.
`enable_rich_text`	boolean	Whether to enable rich text output, `true` or `false`.
`enable_session_file`	boolean	Whether to enable the session file feature, `true` or `false`.
`hybrid_rerank`	object	Global fusion rerank config (search scene). See the sub-field table below.
`kb_search_configs`	array<object>	List of knowledge base retrieval configurations. See the element table below.
`max_completion_tokens`	integer	Maximum generation tokens. Must be >= 1.
`max_num_llm_calls`	integer	Maximum number of LLM calls for the agent.
`rerank_top_n`	integer	Fusion rerank Top N (search scene). Range [1, 20].
`session_file_max_parse_length`	integer	Maximum parsing length for session files. Must be less than the model's max_context_length.
`temperature`	number	Model sampling temperature, range [0, 2].
`anti_leak_prompt`	string	Anti-leak prompt.
`refusal_prompt`	string	Refusal prompt.
`credibility_prompt`	string	Credibility prompt.
`enable_thinking`	boolean	Whether thinking mode is enabled.
`enable_temperature`	boolean	Whether a custom temperature is applied.
`enable_credibility`	boolean	Whether credibility checking is enabled.
`enable_max_completion_tokens`	boolean	Whether the max completion tokens limit is applied.
`session_file_parse_mode`	string	Parsing mode for session files.
`user_system_prompt`	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	Type	Description
`credibility_level`	string	Knowledge base credibility level, e.g. `high`, `medium`, `low`.
`dense_similarity_top_k`	integer	Top-K quantity returned by dense retrieval.
`id`	string	Associated knowledge base Pipeline ID.
`rerank`	object	Reranking configuration. See the sub-field table below.
`rerank_min_score`	number	Minimum rerank score threshold. Chunks with a score below this value are filtered out.
`rerank_top_n`	integer	Top-N quantity retained after reranking.
`search_filters`	array	Retrieval filter conditions, validated against the knowledge base schema.
`sparse_similarity_top_k`	integer	Sparse retrieval Top K. Range [1, 100].
`weight`	number	Knowledge base weight.
`name`	string	Knowledge Base name.
`desc`	string	Knowledge Base description.
`enable_rewrite`	boolean	Whether query rewriting is enabled for this Knowledge Base.

kb_search_configs[].rerank sub-fields

Field	Type	Description
`model_name`	string	Reranking model name, e.g. `gte-rerank-hybrid`.
`rerank_instruct`	string	Custom rerank instruction, only effective when `rerank_mode` is `custom`. Max 500 characters.
`rerank_mode`	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	Type	Description
`model_name`	string	Fusion rerank model code. For VL knowledge bases, only multimodal models are supported; otherwise all rerank models are supported.
`rerank_mode`	string	Fusion rerank mode: `qa`, `similar`, or `custom`. `rerank_instruct` is automatically cleared when not in `custom` mode.
`rerank_instruct`	string	Custom fusion rerank instruction, only effective when `rerank_mode` is `custom`. Max 500 characters.

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