在 AgentCore 中连接百炼知识库

创建并准备百炼知识库

1. 在百炼华北 2（北京）地域创建业务空间和知识库，创建和管理方法见百炼知识库。

2. 向知识库导入文档或结构化数据。

3. 等待文件解析和索引构建完成。

   建议先在百炼控制台执行命中测试，确认查询能够召回预期内容。

准备执行角色

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sfm:Retrieve",
      "Resource": "*"
    }
  ]
}

托管Harness Agent使用知识库

1. 在 Agent 的工具配置中添加已经创建的百炼知识库连接。

2. 保存并重新发布或启动 Agent，使最新配置生效。

3. 与 Agent 对话，调用知识库进行测试，例如：

请先查询产品知识库，再说明产品的安装步骤，并标明依据的文档内容。

高代码 Agent使用知识库

当您已经在 AgentCore 上安装好知识库模板后，您可以在 SDK 中连接并调用您的知识库。

在 SDK 中通过 mcp 连接并查询您的百炼知识库：

import asyncio
import os
from agentcore import AsyncAgentCore

KNOWLEDGE_BASE_NAME = os.environ["KNOWLEDGE_BASE_NAME"]

async def main():
    async with AsyncAgentCore.auto() as core:
        mcp = await core.mcp(KNOWLEDGE_BASE_NAME)
        result = await mcp.call_tool(
            "search_bailian_knowledgebase",
            {"query": "公司的产品如何安装？"},
        )
        print(result)
asyncio.run(main())

元数据过滤

过滤条件使用 search_filters 表达。每个数组元素是一个过滤组，过滤组之间以及同一个过滤组内不同字段之间均使用 AND 关系。

精确匹配示例：

{
  "query": "查询平台团队的高级研发人员",
  "search_filters": [
    {
      "department": "平台研发",
      "level": 3
    }
  ]
}

多值匹配与范围匹配示例：

{
  "query": "查询成年研发人员",
  "search_filters": [
    {
      "department": ["研发", "平台"]
    },
    {
      "age": {
        "gte": 18,
        "lt": 60
      }
    }
  ]
}

支持的运算符如下：

过滤字段必须是知识库中实际存在且可用于过滤的元数据字段。标签字段 tags 的数组值使用 OR 关系，如需同时满足多个标签，请将标签拆到不同过滤组中；过滤条件的完整语法见使用 SearchFilters 提高知识库召回准确性。

返回结果

检索成功时返回相关文本切片、相关性得分和文档元数据；没有命中时，结果数组可能为空。

{
  "data": [
    {
      "text": "第一步：下载并安装客户端……",
      "score": 0.91,
      "metadata": {
        "source": "product-manual.md",
        "category": "安装指南"
      }
    }
  ],
  "query": "产品的安装步骤是什么"
}

检索失败时会返回工具调用错误。百炼服务错误通常包含状态、错误码、错误信息和 RequestId，排查问题时请保留 RequestId。

创建连接时看不到业务空间或知识库

• 确认已选择华北 2（北京）。

• 确认当前登录账号有权查看目标业务空间。

• 确认知识库已经创建完成。

• 确认知识库与所选业务空间一致。

返回 sfm:Retrieve 无权限

依次检查以下几点：

1. 执行角色是否具有 sfm:Retrieve，或是否已绑定 AliyunBailianDataFullAccess。

2. 是否误用了不包含 Retrieve 的 AliyunBailianDataReadOnlyAccess。

3. 执行角色是否已作为 RAM 角色加入目标百炼业务空间。

4. 业务空间授权是否包含知识库及应用数据的操作权限。

5. 创建连接时选择的业务空间和知识库是否匹配。

检索成功但没有召回内容

• 先在百炼控制台使用同一查询执行命中测试。

• 确认文档解析和索引构建已完成。

• 暂时移除元数据过滤，确认是否因过滤条件过严导致空结果。

• 检查过滤字段名、字段类型和值是否与知识库元数据一致。

• 尝试在问题中增加产品名、术语或文档标题等上下文。

Agent 没有使用知识库

• 确认知识库连接状态正常。

• 确认该连接已经添加到当前 Agent。

• 重新保存并发布 Agent，使最新配置生效。

• 检查提示词中是否已说明知识库用途和需要检索的场景。