Service Channels - 阿里云百炼 Agent Studio

After knowledge retrieval and Q&A services are published, they can be integrated into your applications through various channels. On the console's Application Integration → Service Channels page, you can view integration information and sample code for each channel.

Comparison of Integration Methods

Channel	Type	Use Case	Description
REST API	REST / SSE	Custom backend services	DashScope HTTP interface, with multi-language SDKs (Python / Java)
MCP Server	MCP Protocol	AI Agent frameworks	Supports clients such as Qoder / Claude Code / Codex
CLI	Command Line	Local debugging / scripts	`bailian-cli`: perform retrieval and Q&A directly in terminal
Agent Skill	Skill Package	Qoder / Claude Code	Integrated as a skill package; automatically loaded by AI coding tools
Bailian Agent	Web	Rapid validation / low-code	Alibaba Cloud Bailian agent application, supports both Agent binding and Workflow binding

REST API

All retrieval and Q&A capabilities are provided via the DashScope API, with service endpoint: https://{workspaceId}.cn-beijing.maas.aliyuncs.com. Authentication:

Authorization: Bearer <API-Key>

API Keys are created on the console API Key page. The system automatically routes requests to the corresponding workspace based on the API Key. Key Endpoints:

Endpoint	Method	Path	Description
Knowledge Search	POST	`/api/v1/indices/knowledge/search`	Application-level hybrid search, driven by knowledge retrieval service configuration; caller only needs to pass `query` and `agent_id`
Knowledge Q&A	POST	`/api/v2/apps/knowledge/chat`	Streaming Q&A, returning SSE events
Low-level Retrieval	POST	`/api/v1/indices/rag/index/retrieve`	Single-knowledge-base retrieval, directly returning vector + keyword recall results — no re-ranking performed at this layer

Example: Knowledge Search API (as provided on the console’s Service Channels page):

curl -X POST 'https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/knowledge/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $DASHSCOPE_API_KEY' \
  -d '{
    "query": "${YOUR_QUERY}",
    "agent_id": "${YOUR_APP_ID}"
  }'

The search scope and strategy (e.g., multi-repo weights, routing, hybrid ranking) are governed by the knowledge retrieval service configuration associated with agent_id. Callers do not need to repeat these parameters in the request. Example: Low-level Retrieval API (specifying knowledge base ID directly):

curl -X POST https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/index/retrieve \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "index_id": "<KnowledgeBaseID>",
    "query": "How do I configure chunking strategies?",
    "top_k": 5
  }'

The low-level single-knowledge-base retrieval API returns raw vector + keyword recall results without re-ranking. To enable Rerank-based fine-grained ranking, configure a hybrid ranking model when creating the retrieval service and invoke it via the Knowledge Search API (agent_id).

For the full list of endpoints, see the API Reference.

MCP Server

MCP (Model Context Protocol) is an open standard enabling AI coding assistants and agent frameworks to directly invoke external tools. After integrating the RAG MCP Server, your AI assistant can retrieve content from knowledge bases during conversations.

Prerequisites

At least one knowledge base has been created and contains parsed documents.
An API Key has been obtained.
A client supporting the MCP protocol is installed (e.g., Qoder, Claude Code, Codex).

Integration Steps

Obtain API Key

Create an API Key on the console API Key page. We recommend storing it as an environment variable:

export DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxxxxx"

Add MCP Server in Client

Based on your client, choose the appropriate configuration method:

Qoder / QoderWork
Claude Code
Codex

Open the MCP configuration file and add the following:

{
  "mcpServers": {
    "rag_mcp": {
      "type": "streamableHttp",
      "url": "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/mcp",
      "headers": {
        "Authorization": "Bearer ${DASHSCOPE_API_KEY}"
      }
    }
  }
}

Run the following command in your terminal:

claude mcp add --transport http rag-mcp-server \
  https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/mcp \
  --header "Authorization: Bearer ${DASHSCOPE_API_KEY}"

Add the following to your Codex configuration file:

[mcp_servers.rag_mcp_server]
url = "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/mcp"
http_headers = {
    "Authorization" = "Bearer ${DASHSCOPE_API_KEY}"
}

Supported starting from Codex v0.120.0.

Verify Connection

After configuration, test knowledge base access in your client. For example, in Claude Code, type:

Help me search “How to create a knowledge base” in the knowledge base.

If the AI assistant successfully invokes the Retrieve tool and returns results, integration is successful.

Connection Details

Item	Value
Endpoint	`https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/mcp`
Protocol Version	MCP 2024-11-05
Transport	Streamable HTTP (POST + GET SSE)
Authentication	`Authorization: Bearer <API-Key>`

Provided Tools

Tool Name	Function	Description
`Retrieve`	Retrieve from knowledge base	Retrieves relevant chunks from a specified knowledge base, supporting hybrid retrieval and Reranking
`ListIndices`	List knowledge bases	Paginated list of knowledge bases under the current workspace

Parameters for Retrieve:

Parameter	Type	Required	Default	Description
`IndexId`	string	Yes	—	Knowledge base index ID
`Query`	string	Yes	—	Query text (must not be empty)
`DenseSimilarityTopK`	integer	No	100	Semantic retrieval top-K count (range: 0–100)
`SparseSimilarityTopK`	integer	No	100	Keyword retrieval top-K count (range: 0–100)
`EnableReranking`	boolean	No	true	Whether to enable re-ranking
`Rerank.ModelName`	string	No	qwen3-rerank	Ranking model; options: `qwen3-rerank`, `qwen3-rerank-hybrid`

The sum of DenseSimilarityTopK and SparseSimilarityTopK must be greater than 1. Using only one retrieval method (e.g., Dense=1, Sparse=0) will result in an error.

The RerankMode, RerankMinScore, RerankTopN, and RerankInstruct parameters in the Rerank object are not supported in the current version and will cause errors if provided. To control re-ranking behavior, use only EnableReranking and Rerank.ModelName.

Parameters for ListIndices:

Parameter	Type	Required	Default	Description
`pageNumber`	integer	No	1	Page number (starting from 1)
`pageSize`	integer	No	10	Number of items per page
`indexName`	string	No	—	Filter by knowledge base name prefix

Supported Clients:

Qoder / QoderWork
Claude Code
Codex (v0.120.0+)
Other MCP-compliant clients

CLI

bailian-cli is a command-line tool for interacting with knowledge bases. No coding required — perform retrieval instantly from your terminal. Ideal for local debugging, script integration, and CI/CD pipelines. Installation commands and usage examples are available on the console’s Service Channels page.

Prerequisites

Node.js (v14 or later) installed
At least one knowledge base created and containing parsed documents
An API Key obtained

Getting Started

Set API Key

Store your API Key as an environment variable — subsequent commands will read it automatically:

export DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxxxxx"

Get Knowledge Base ID

Navigate to the console’s Data Ingestion → Knowledge Management page, click your target knowledge base, and copy its ID (e.g., r0t4r2c4ig).

Run Your First Retrieval

No installation needed — run directly using npx:

npx bailian-cli knowledge retrieve \
  --api-key "$DASHSCOPE_API_KEY" \
  --index-id "your-knowledge-base-id" \
  --query "your-question"

This outputs retrieved document chunks along with relevance scores.

Enable Reranking

Add the --rerank flag to apply secondary ranking to improve result relevance:

npx bailian-cli knowledge retrieve \
  --api-key "$DASHSCOPE_API_KEY" \
  --index-id "r0t4r2c4ig" \
  --query "Bailian" \
  --rerank true \
  --dense-similarity-top-k 80 \
  --sparse-similarity-top-k 20 \
  --rerank-top-n 4 \
  --rerank-model "qwen3-rerank-hybrid" \
  --rerank-mode "similar"

Parameter Reference

Parameter	Required	Default	Description
`--api-key`	Yes	—	DashScope API Key
`--index-id`	Yes	—	Knowledge base index ID
`--query`	Yes	—	Query text
`--dense-similarity-top-k`	No	100	Semantic retrieval top-K count (range: 0–100)
`--sparse-similarity-top-k`	No	100	Keyword retrieval top-K count (range: 0–100)
`--rerank`	No	—	Enable re-ranking
`--rerank-top-n`	No	5	Number of results returned after re-ranking
`--rerank-model`	No	qwen3-rerank	Ranking model; options: `qwen3-rerank-hybrid`
`--rerank-mode`	No	qa	Ranking mode; options: `similar`, `custom`

Run npx bailian-cli knowledge retrieve --help to view all parameter details.

CLI also supports legacy AK/SK authentication (--access-key-id + --access-key-secret + --workspace-id), but --api-key is recommended. When both are provided, --api-key takes precedence.

Agent Skill

Integrate your knowledge base as a skill package into AI coding tools like Qoder or Claude Code. Install URL: https://skills.aliyun.com/skills/alibabacloud-bailian-rag-knowledgebase. You can obtain this link on the console’s Service Channels → Agent Skill page. Once installed, AI coding tools automatically detect and load knowledge base retrieval capabilities — no manual configuration required.

Bailian Agent

KnowledgeStudio knowledge bases can be integrated as external capabilities into Alibaba Cloud Bailian agent applications, supporting two binding methods:

Method 1: Agent Binding (Recommended)

Suitable for new-generation agent applications (Agent 2.0). The knowledge base functions as one of the agent’s skills, invoked autonomously by the agent according to task planning — unified scheduling with other tools (e.g., MCP).

In the Bailian console: Create Application → Agent Application → Agent 2.0
Under the “Knowledge Base” section, select “External Knowledge Base → KnowledgeStudio”
Paste your API Key and knowledge base ID, then publish

Method 2: Workflow Binding

Suitable for Bailian workflow applications. Break down complex tasks into ordered nodes (e.g., LLM node, intent classification node, end node), and use KnowledgeStudio as a “Knowledge Base Retrieval Node” within the workflow.

In the Bailian console: Create Application → Workflow Application
Drag a “Knowledge Base Retrieval” node onto the canvas and select “KnowledgeStudio” as the source
Connect start / LLM / end nodes, then publish as an application

Selection Guidance

Method	Use Case
Agent Binding	Tasks are dynamic, require multi-step reasoning, and benefit from autonomous agent decision-making. E.g., enterprise intelligent Q&A, complex research tasks
Workflow Binding	Processes are fixed and require strict execution order control. E.g., report generation, customer service routing, diagnostic assistance

If your application is built on third-party platforms like Dify or Coze, refer to Third-Party Integration for detailed configuration guidance.

​Comparison of Integration Methods

​REST API

​MCP Server

​Prerequisites

​Integration Steps

​Connection Details

​Provided Tools

​CLI

​Prerequisites

​Getting Started

​Enable Reranking

​Parameter Reference

​Agent Skill

​Bailian Agent

​Method 1: Agent Binding (Recommended)

​Method 2: Workflow Binding

​Selection Guidance

Comparison of Integration Methods

REST API

MCP Server

Prerequisites

Integration Steps

Connection Details

Provided Tools

CLI

Prerequisites

Getting Started

Enable Reranking

Parameter Reference

Agent Skill

Bailian Agent

Method 1: Agent Binding (Recommended)

Method 2: Workflow Binding

Selection Guidance