按智能体检索知识库

接口介绍

接口路径:POST /api/V1/open-portal/app/retriever/search/agent_kb

按智能体检索知识库内容:传入智能体 Code 和检索关键词,从指定智能体关联的知识库中查询相关文档片段或问答内容,并返回匹配结果列表。

  • 支持通过 kb_names 指定知识库名称列表以限定检索范围。
  • 支持控制返回结果数量、是否重排、是否优先检索 QA,以及结果分数阈值。
  • 返回结果包含文档 ID、文件名、问题、答案、正文内容、内容类型、匹配分数及相关元数据。
  • 操作者用户 ID 由平台网关注入 X-App-User-Id,调用方不要自行设置。

请求参数

字段类型必填说明
agent_codestring是智能体 Code
querystring是检索内容
kb_namesarray of string否知识库名称列表,限定检索范围,默认 []
top_kinteger否返回 Top K 个结果,默认 10
rerankboolean否是否重排结果,默认 true
check_qa_firstboolean否是否优先检索 QA,默认 true
score_thresholdnumber否结果分数阈值,默认 0

调用示例

接口采用 AK/SK 签名鉴权,请求头需携带 X-App-Id、X-App-Key、X-Timestamp、X-Nonce、X-Signature。签名 = HMAC-SHA256(AppSecret, METHOD\nPATH\nTIMESTAMP\nNONCE),只使用 URL path,不含 query。

下方命令可直接复制运行:替换凭证后先跑一次即可验证连通性(在线调试),再按「请求参数」修改 -d 内容调试其它入参。

bash
APP_ID="app_xxxxxxxx"
APP_KEY="ak_xxxxxxxx"
APP_SECRET="sk_xxxxxxxx"
BASE_URL="https://open.agibot.com"
API_PATH="/api/V1/open-portal/app/retriever/search/agent_kb"

TS_MS=$(( $(date +%s) * 1000 ))
NONCE="$(head -c 16 /dev/urandom | od -An -tx1 | tr -d ' \n')"
SIGNATURE=$(printf 'POST\n%s\n%s\n%s' "$API_PATH" "$TS_MS" "$NONCE" \
  | openssl dgst -sha256 -hmac "$APP_SECRET" | sed 's/^.* //')

curl -sS -X POST "$BASE_URL$API_PATH" \
  -H "Content-Type: application/json" \
  -H "X-App-Id: $APP_ID" \
  -H "X-App-Key: $APP_KEY" \
  -H "X-Timestamp: $TS_MS" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE" \
  -d '{
    "agent_code": "AI_AGENT_28159402",
    "query": "远征",
    "kb_names": ["产品手册"],
    "top_k": 10,
    "rerank": true,
    "check_qa_first": true,
    "score_threshold": 0
  }'

返回参数

字段类型说明
codeinteger状态码,成功为 0
successboolean请求是否成功
messagestring错误提示;成功时为空
dataarray匹配结果列表
data.idstring结果 ID
data.doc_idstring文档 ID
data.filenamestring文档名称
data.contentstringchunk 内容
data.questionstring问题(QA 内容时返回)
data.answerstring答案(QA 内容时返回)
data.content_typestringchunk 类型
data.scorenumber结果分数
data.metadataobject结果元信息

返回示例

json
{
  "code": 0,
  "success": true,
  "message": "",
  "data": [
    {
      "id": "chunk-1",
      "doc_id": "doc-1",
      "filename": "产品手册.pdf",
      "content": "远征机器人支持……",
      "question": null,
      "answer": null,
      "content_type": "document",
      "score": 0.92,
      "metadata": {}
    }
  ]
}

常见错误

  • 缺少 agent_code 或 query。
  • 智能体不存在或不属于当前租户。
  • 智能体未关联任何知识库。
  • 鉴权签名错误或过期。