接口介绍
本接口（
/v3/skill/search）用于按查询文本搜索匹配的 Skill，支持关键词、语义向量和混合搜索三种模式。功能说明如下：搜索模式：支持
bm25（关键词）、embedding（语义）和 hybrid（混合）三种模式，默认为混合模式。结果排序：返回带相关性评分（
score）的 Skill 列表，结果按 score 降序排列。搜索范围：默认在当前 Agent 作用域内搜索，传入
scope="team" 可跨当前团队下全部 Agent 搜索。Method 与 URL
POST https://memory.tdai.tencentyun.com/v3/skill/search
使用示例
curl -i -X POST \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer *********************************' \\-H "x-tdai-service-id: tdai-mem-xxxxxxxx" \\https://memory.tdai.tencentyun.com/v3/skill/search \\-d '{"query":"Python type hints usage","top_k":10,"mode":"hybrid"}'
请求参数
Body 参数
参数 | 是否必选 | 参数含义 | 配置方法及要求 |
query | 是 | 搜索查询文本。 | 数据类型：String。 |
top_k | 否 | 返回结果数量上限。 | 数据类型：Integer。 |
mode | 否 | 搜索模式。 | 数据类型：String。 取值范围： bm25（关键词）、embedding（语义）、hybrid（混合，默认）。 |
scope | 否 | 搜索范围。 | 数据类型：String。 传 "team" 时跨当前团队下全部 Agent 搜索。 |
team_id | 否 | 团队 ID，覆盖鉴权凭证中的默认值。 | 数据类型：String。 |
agent_id | 否 | Agent ID，覆盖鉴权凭证中的默认值。 | 数据类型：String。 |
user_id | 否 | 用户 ID，覆盖鉴权凭证中的默认值。 | 数据类型：String。 |
task_id | 否 | Task ID，覆盖鉴权凭证中的默认值。 | 数据类型：String。 |
响应示例
{"code":0,"message":"ok","request_id":"req-abc123","data":{"items":[{"skill_id":"skill-abc123","name":"python-tips","score":0.95,"content":"---\\nname: python-tips\\n...","version":3}]}}
响应参数说明
参数名（一级） | 参数名（二级） | 参数含义 |
data | items | 匹配结果列表，按相关性得分降序排列。 |
| items[].skill_id | Skill ID。 |
| items[].name | Skill 名称。 |
| items[].score | 相关性得分（float）。 |
| items[].content | Skill 内容。 |
| items[].version | 当前版本号。 |
错误码
HTTP 状态码 | 错误信息 | 说明 |
400 | request: Invalid input | 请求参数不合法，如 query 为空。 |
401 | Missing or invalid Authorization header | Bearer API Key 缺失或格式不正确。 |
422 | Schema validation failed | 参数格式校验通过但业务规则不通过。 |
500 | Internal error | 服务内部错误，可有限重试。 |
