Overview of Knowledge Base Connections

Updated at:
Copy as MD

A knowledge base connection connects an existing external knowledge base to AgentCore so that Agents can retrieve content from the knowledge base and answer questions based on it. Documents and indexes in the knowledge base do not need to be migrated to AgentCore; they remain stored and managed by the original knowledge base product. AgentCore establishes the knowledge base connection and exposes the knowledge base's retrieval tools to Agents through the Model Context Protocol (MCP). You can create, view, and associate connections from the knowledge base connection list without first learning the MCP configuration. To view underlying service details, tool capabilities, or perform secondary development, go to Tool Management.

What is a knowledge base connection

A knowledge base connection does not recreate a knowledge base inside AgentCore; it establishes an access relationship between AgentCore and an existing knowledge base. After a connection is created, AgentCore exposes the knowledge base's retrieval capability to Agents as tools. At runtime, an Agent can call the appropriate tool as needed and use the returned knowledge content to generate answers. A knowledge base connection involves the following objects:

Object

Description

External knowledge base

The knowledge base that actually stores documents, chunks, and indexes. AgentCore supports connecting Tablestore (OTS) or Model Studio (Bailian) knowledge bases.

Knowledge base connection

The resource AgentCore uses to access an external knowledge base. It records the knowledge base type, connection status, and required connection configuration.

MCP tool

The technical view of a knowledge base connection from the tool system perspective, that is, the MCP Server that provides knowledge retrieval capability to Agents. It can contain one or more retrieval tools.

Retrieval tool

The specific capability that an MCP Server provides to Agents, including the tool name, description, and parameter schema.

Agent association

Determines which Agents can use the knowledge base connection. After you create a connection, you must still go to the Agent's Agent Assets to select and mount it.

Knowledge bases and tool management

After you create a knowledge base connection from an official knowledge base template, AgentCore generates an MCP tool. The following two views show the same knowledge base resource; you do not need to create or maintain them separately:

  • Asset Management > Knowledge Base (knowledge base connection list): for knowledge base users, used to create, view, and manage knowledge base connections.

  • Asset Management > Tool Management > My Tools: for tool and MCP management, used to view underlying service details, tool capabilities, runtime configuration, and secondary development. For related operations, see Manage MCP Servers.

    Tool Management > Tool Marketplace also displays official knowledge base templates, and the Knowledge Base Connection list also shows official knowledge base templates installed from the Tool Marketplace. For common knowledge base usage, we recommend using the Asset Management > Knowledge Base entry. To troubleshoot connections, view specific tools, or extend implementations, go to Tool Management.

Use cases

When your business documents already reside in a Tablestore (OTS) knowledge base or a Model Studio (Bailian) knowledge base and you want Agents to use this content directly, you can create a knowledge base connection. This approach is suitable for continuing to use the original knowledge base's data management, permissions, and retrieval capabilities while mounting and using the knowledge content for Agents through AgentCore.

AgentCore only provides the ability to connect to and retrieve from knowledge bases; it does not support adding, updating, or deleting knowledge base documents. Document upload and update, chunking, vector indexing, metadata, and the knowledge base's default retrieval configuration are all managed by the Tablestore (OTS) or Model Studio (Bailian) provider. You must maintain them in the original knowledge base product's management console. After maintenance, Agents use the updated knowledge content through the connection.

Supported knowledge base types

AgentCore currently provides two official knowledge base connection entries. Choose the knowledge base connection type that matches the product where your business documents reside:

Knowledge base type

Scope

Tablestore (OTS) knowledge base

Connects an existing Tablestore (OTS) knowledge base. For prerequisites and configuration items, see Connect a Tablestore OTS Knowledge Base in AgentCore.

Model Studio (Bailian) knowledge base

Connects an existing Alibaba Cloud Model Studio (Bailian) knowledge base. For prerequisites and configuration items, see Connect an Alibaba Cloud Model Studio Knowledge Base in AgentCore.

Create and use a knowledge base connection

Before you create a knowledge base connection, note the following limits:

  • One knowledge base connection corresponds to one external knowledge base. To use multiple knowledge bases, create separate connections and add them to Agents as needed.

  • Connection parameters for template-managed connections are determined at creation. To switch the instance, business workspace, or knowledge base, delete the original connection and create a new one.

  • The knowledge base connection catalog only includes MCPs in the template-managed state. For those converted to free editing, view and manage them in the tool catalog.

Create a knowledge base connection

Open the Knowledge Base Connection list, select the knowledge base type to connect, and fill in the knowledge base metadata as prompted. Different knowledge base types require different prerequisites and configuration items; complete the connection for the corresponding type per Connect a Tablestore OTS Knowledge Base in AgentCore or Connect an Alibaba Cloud Model Studio Knowledge Base in AgentCore.

  1. Log on to the AgentCore console.

  2. Go to the target Workspace.

  3. In the left-side navigation pane, choose Asset Management > Knowledge Base.

  4. Click Create Knowledge Base Connection.

  5. Select Tablestore (OTS) or Model Studio (Bailian) knowledge base.

  6. Fill in the connection configuration, such as the knowledge base identifier, execution role, and optional log configuration.

  7. Click Install and Deploy, and wait for the connection status to become normal.

    After creation, the Knowledge Base Connection list and Tool Management > My Tools both display this resource.

Associate a knowledge base with a managed Harness Agent

Creating a knowledge base connection does not automatically grant all Agents permission to use it. The retrieval capability is provided to an Agent as a tool only after you add the connection to that Agent. For the purpose and update method of each tab on the configuration page, see Manage Agent.

  1. Go to the configuration page of the target Agent.

  2. Switch to the Knowledge Base tab under Agent Asset Configuration and select the knowledge base connection.

  3. Update the Agent.

    The Tools tab also displays the same connection. The Knowledge Base tab is a filtered view for knowledge base connection MCPs, while the Tools tab is a unified view of all MCP tools; mounting or removing from either tab syncs the result.

View retrieval tools and parameters

The Knowledge Base Connection list mainly shows the connection itself. To view the complete tool name, tool description, and invocation parameters:

  1. Go to Asset Management > Tool Management > My Tools.

  2. Find the MCP tool with the same name as the knowledge base connection.

  3. Go to the Tool Details page.

  4. View the tools and parameters provided by the MCP Server in the tool list.

    The tool list is read by AgentCore from deployed services. If the tool list is empty or fails to load, first check the deployment status and runtime logs per Manage MCP Servers.

When an Agent uses a knowledge base, AgentCore provides the tool name, description, and parameter schema to the model. The model decides whether to call the retrieval tool based on the question and Agent instructions, and generates the corresponding tool parameters.

Convert to free editing

After you quickly create a knowledge base connection from Asset Management > Knowledge Base, or install the corresponding official template from the Tool Marketplace, the generated MCP tool is in the template-managed state by default. In the template-managed state, the knowledge base connection remains associated with the official knowledge base template and its application version; the MCP tool's protocol, port, basic runtime configuration, and core connection configuration are managed uniformly by the template and cannot be modified by users.

Important

Converting to free editing is a one-way operation; the same MCP tool cannot be restored to the template-managed state. To use the official template again, create a new knowledge base connection from Asset Management > Knowledge Base.

Scenarios suitable for conversion

If you need secondary development, you can convert a template-managed MCP tool to free editing. Scenarios suitable for conversion include:

  • Modifying the retrieval tool name, description, or parameter schema.

  • Adding new MCP tools.

  • Adding custom processing logic before or after knowledge base invocation.

  • Replacing the code package, or adjusting the MCP tool's runtime configuration.

Confirm before conversion

Before conversion, we recommend confirming the following:

  • Whether your current requirement truly requires modifying the MCP tool's code or runtime configuration.

  • Whether you have saved the custom code package and configuration.

  • Whether the Agents using this connection can accommodate the planned tool changes.

  • Whether you accept maintaining this resource as a regular MCP tool going forward.

Perform the conversion

Go to Asset Management > Tool Management > My Tools > Tool Details and convert the template-managed MCP tool to free editing. After conversion, the resource becomes a regular MCP tool in Tool Management > My Tools; thereafter, maintain the code package and runtime configuration as a regular MCP tool per Manage MCP Servers.

What happens after conversion

  • After conversion, the current deployment continues to be used; the original MCP tool's availability, deployment, and gateway address remain unchanged, and no redeployment is needed.

  • You can use the regular MCP tool's editing capability to modify the code package and runtime configuration; when a change requires redeployment, AgentCore publishes a new deployment version.

  • Connection configuration is maintained through the regular MCP tool's editing capability.

    If you modify the tool name, tool description, or parameter schema after conversion, go to the Tool Details page again to check the tool list, and republish or restart the relevant Agents so they use the latest tool definition.