MCP,Model Context Protocol,JSON-RPC,Agentic Memory,智能体记忆,MCP接入-智能开放搜索 OpenSearch(Open Search)-阿里云帮助中心

前提条件

已获取API-KEY鉴权信息。详情请参见认证和鉴权。
已获取服务调用地址。详情请参见获取服务接入地址。

工具总览

MCP接口共提供18个工具，分为4个类别：

#	工具名	分类	说明
1	memory_add	Memory	存储记忆（异步）
2	memory_event_status_get	Memory	查询异步事件状态
3	memory_search	Memory	语义搜索记忆
4	memory_get	Memory	获取单条记忆
5	memory_get_all	Memory	按精确条件分页枚举记忆
6	memory_update	Memory	更新记忆内容
7	memory_delete	Memory	删除记忆
8	skill_list	Skill	列出用户技能
9	skill_search	Skill	搜索技能
10	skill_view	Skill	获取完整技能
11	skill_manage	Skill	管理技能（创建、编辑、补丁修改、删除、文件管理）
12	kb_docs_search	Knowledge Base	搜索文档
13	kb_nodes_search	Knowledge Base	搜索节点
14	kb_doc_structure_get	Knowledge Base	获取文档目录结构
15	kb_node_content_get	Knowledge Base	获取节点内容
16	kb_doc_grep	Knowledge Base	文档文本搜索
17	kb_doc_read	Knowledge Base	读取文档内容
18	hybrid_search	混合检索	跨数据源混合检索（Hybrid Search）

协议说明

请求端点

所有MCP工具调用共享同一端点：

{host}/v1/agentic-memory/mcp

其中host为服务调用地址，获取方式请参见获取服务接入地址。

Header参数

参数	类型	必填	描述	示例值
Content-Type	String	是	请求类型	application/json
Accept	String	是	接受响应类型	application/json
Authorization	String	是	API-KEY鉴权信息	Bearer OS-d1**2a

请求体格式

所有工具调用使用统一的JSON-RPC 2.0格式：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "<工具名称>",
    "arguments": { ... }
  }
}

可通过tools/list方法查询所有可用工具及其参数定义：

{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}

响应体格式

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "<JSON 字符串>"
      }
    ],
    "structuredContent": { ... },
    "isError": false
  }
}

result.content[0].text为工具返回值的JSON序列化字符串，需二次解析。

result.structuredContent为已解析的JSON对象，可直接使用，无需二次解析。

Memory工具

Memory工具用于管理用户长期记忆的写入、查询、更新和删除。Memory ID前缀为m-，异步事件ID前缀为me-。

memory_add — 存储Memory

从消息内容中智能提取用户偏好信息并存储为Memory。存储过程为异步处理，接口返回事件ID（event_id），可通过memory_event_status_get获取处理结果。

参数

参数	类型	必填	描述	示例值
messages	String/Object/Array	是	消息内容，支持三种格式：String（简单文本）、Object（单条消息）、Array（多轮对话）。	"我喜欢喝咖啡"
user_id	String	是	用户ID。	your_user_id
agent_id	String	否	Agent ID，仅作为过滤维度使用。	your_agent_id
run_id	String	否	Run ID，仅作为过滤维度使用。	your_run_id
metadata	Object	否	自定义键值对，与Memory一同存储。`metadata.timestamp`（ISO日期）用作时间锚点。	{"source": "chat"}
infer	Boolean	否	是否对消息进行语义抽取以生成Memory。默认true；置为false则按原文整体落库。	true

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v1/agentic-memory/mcp' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "memory_add",
    "arguments": {
      "messages": [
        {"role": "user", "content": "我喜欢喝咖啡，帮我推荐"},
        {"role": "assistant", "content": "为您推荐美式咖啡..."}
      ],
      "user_id": "your_user_id",
      "metadata": {"source": "chat"}
    }
  }
}'

响应示例

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"event_id\":\"me-06bde8b5-d123-43cf-9898-64d08fbfaafc\",\"status\":\"PENDING\"}"
      }
    ],
    "structuredContent": {
      "event_id": "me-06bde8b5-d123-43cf-9898-64d08fbfaafc",
      "status": "PENDING"
    },
    "isError": false
  }
}

memory_event_status_get — 查询事件状态

查询存储Memory的异步事件处理状态及生成的Memory列表。

参数

参数	类型	必填	描述	示例值
event_id	String	是	存储Memory时返回的事件ID，前缀为`me-`。	me-06bde8b5-d123-43cf-9898-64d08fbfaafc

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v1/agentic-memory/mcp' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "memory_event_status_get",
    "arguments": {
      "event_id": "me-06bde8b5-d123-43cf-9898-64d08fbfaafc"
    }
  }
}'

响应示例

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"event_id\":\"me-06bde8b5-d123-43cf-9898-64d08fbfaafc\",\"status\":\"SUCCEEDED\",\"memory_ids\":[\"m-8d0417d7-9368-4777-9016-b7ee6daeb70b\"]}"
      }
    ],
    "structuredContent": {
      "event_id": "me-06bde8b5-d123-43cf-9898-64d08fbfaafc",
      "status": "SUCCEEDED",
      "memory_ids": ["m-8d0417d7-9368-4777-9016-b7ee6daeb70b"]
    },
    "isError": false
  }
}

memory_search — 搜索Memory

根据查询条件搜索Memory，采用BM25和向量多路召回技术。

参数

参数	类型	必填	描述	示例值
query	String	是	搜索关键词。	咖啡推荐
filters	Object	是	过滤条件，必须为`{"AND": [...]}`格式，其中必须包含`user_id`。	{"AND": [{"user_id": "your_user_id"}]}
top_k	Int	否	返回结果数量，下限1，上限1000，默认10。	10
threshold	Float	否	相似度阈值，取值范围0~1，低于此分数的结果不返回。	0.5
rerank	Boolean	否	启用重排序以提高精度（可能增加延迟），默认false。	false

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v1/agentic-memory/mcp' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "memory_search",
    "arguments": {
      "query": "咖啡推荐",
      "filters": {"AND": [{"user_id": "your_user_id"}]},
      "top_k": 10
    }
  }
}'

响应示例

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"results\":[{\"id\":\"m-8d0417d7-9368-4777-9016-b7ee6daeb70b\",\"memory\":\"助手为用户推荐了美式咖啡\",\"score\":0.9151,\"metadata\":{\"source\":\"chat\"},\"created_at\":\"2026-06-02T08:39:21.482047Z\",\"updated_at\":\"2026-06-02T08:39:21.482047Z\"}],\"total\":1}"
      }
    ],
    "isError": false
  }
}

memory_get — 获取Memory

根据Memory ID获取单条Memory详情。

参数

参数	类型	必填	描述	示例值
memory_id	String	是	Memory ID，前缀为`m-`。	m-8d0417d7-9368-4777-9016-b7ee6daeb70b

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v1/agentic-memory/mcp' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "memory_get",
    "arguments": {
      "memory_id": "m-8d0417d7-9368-4777-9016-b7ee6daeb70b"
    }
  }
}'

响应示例

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\":\"m-8d0417d7-9368-4777-9016-b7ee6daeb70b\",\"memory\":\"助手为用户推荐了美式咖啡\",\"user_id\":\"your_user_id\",\"agent_id\":\"your_agent_id\",\"metadata\":{\"source\":\"chat\"},\"created_at\":\"2026-06-02T08:39:21.482047Z\",\"updated_at\":\"2026-06-02T08:39:21.482047Z\"}"
      }
    ],
    "isError": false
  }
}

memory_get_all — 分页枚举Memory

按精确过滤条件分页枚举Memory，不做语义相关性排序。响应包含count（匹配到的Memory总数）与results（当前页的Memory列表）。如需按相关性召回，请使用memory_search。

参数

参数	类型	必填	描述	示例值
filters	Object	是	精确匹配的过滤条件，多个条件之间为AND关系。必须包含非空的`user_id`，可选`agent_id`、`run_id`，也可附加其他metadata过滤条件。说明此处为扁平结构，不要使用`memory_search`的`{"AND": [...]}`包装格式，否则报错。	{"user_id": "your_user_id"}
page	Int	否	页码，从1开始。默认值为1。	1
page_size	Int	否	单页返回的Memory条数，取值范围为1~200。默认值为100。	5

说明

当page × page_size同时小于count和10000（可分页窗口上限）时，可递增page继续获取下一页。

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v1/agentic-memory/mcp' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 18,
  "method": "tools/call",
  "params": {
    "name": "memory_get_all",
    "arguments": {
      "filters": {
        "user_id": "your_user_id"
      },
      "page": 1,
      "page_size": 5
    }
  }
}'

响应示例

{
  "jsonrpc": "2.0",
  "id": 18,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"count\":1,\"results\":[{\"id\":\"m-0780fe5f-a60f-4215-96b1-2e4fa6a6bc0b\",\"memory\":\"用户经常出差去杭州，偏好入住西湖附近的酒店\",\"user_id\":\"your_user_id\",\"agent_id\":null,\"run_id\":null,\"metadata\":{\"org_id\":\"150102724\"},\"created_at\":\"2026-08-11T14:55:34.071160+08:00\",\"updated_at\":\"2026-08-11T14:55:34.071160+08:00\",\"score\":null}]}"
      }
    ],
    "isError": false
  }
}

memory_update — 更新Memory

根据Memory ID更新已有记忆内容。

参数

参数	类型	必填	描述	示例值
memory_id	String	是	Memory ID，前缀为`m-`。	m-8d0417d7-9368-4777-9016-b7ee6daeb70b
text	String	是	更新后的记忆内容。	用户偏好拿铁咖啡

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v1/agentic-memory/mcp' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "memory_update",
    "arguments": {
      "memory_id": "m-8d0417d7-9368-4777-9016-b7ee6daeb70b",
      "text": "用户偏好拿铁咖啡"
    }
  }
}'

响应示例

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\":\"m-8d0417d7-9368-4777-9016-b7ee6daeb70b\",\"memory\":\"用户偏好拿铁咖啡\",\"updated_at\":\"2026-06-02T08:40:18.428159Z\"}"
      }
    ],
    "isError": false
  }
}

memory_delete — 删除Memory

根据Memory ID删除一条Memory。

参数

参数	类型	必填	描述	示例值
memory_id	String	是	Memory ID，前缀为`m-`。	m-8d0417d7-9368-4777-9016-b7ee6daeb70b

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v1/agentic-memory/mcp' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "memory_delete",
    "arguments": {
      "memory_id": "m-8d0417d7-9368-4777-9016-b7ee6daeb70b"
    }
  }
}'

响应示例

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"message\":\"Memory m-8d0417d7-9368-4777-9016-b7ee6daeb70b deleted successfully\"}"
      }
    ],
    "isError": false
  }
}

Skill工具

Skill工具用于管理可复用技能的查询、查看和管理。Skill ID前缀为s-。

skill_list — 列出用户技能

列出指定用户的所有技能。

参数

参数	类型	必填	描述	示例值
user_id	String	是	用户ID。	your_user_id
tags	Array[String]	否	按标签过滤技能列表。	["beverage", "coffee"]
limit	Int	否	返回结果数量上限，最多30个技能。	10
agent_id	String	否	按Agent ID过滤技能列表。	my_agent
scope	String	否	检索范围，可选值：`user`、`library`、`all`。省略则搜索全部。	user

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v1/agentic-memory/mcp' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "skill_list",
    "arguments": {
      "user_id": "your_user_id"
    }
  }
}'

响应示例

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"object\":\"list\",\"data\":[{\"id\":\"s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166\",\"name\":\"咖啡推荐技能\",\"description\":\"咖啡推荐技能\",\"version\":\"0.1.0\",\"owner\":\"your_user_id\",\"agent_id\":\"\",\"tags\":[\"beverage\",\"coffee\"],\"triggers\":[],\"metadata\":{\"origin\":\"uploaded\"},\"resource_paths\":[],\"updated_at\":\"2026-06-02T08:39:21+00:00\"}],\"user\":\"your_user_id\"}"
      }
    ],
    "isError": false
  }
}

skill_search — 搜索Skill

根据查询条件语义搜索可复用Skill。

参数

参数	类型	必填	描述	示例值
query	String	是	搜索关键词。	登录提示
user_id	String	是	用户ID，参与个人技能空间搜索。	your_user_id
limit	Int	否	返回结果数量上限。	10
min_score	Float	否	最低相似度分数。	0.5
scope	String	否	检索范围，可选值：`user`、`library`、`all`。省略则搜索全部。	user
agent_id	String	否	Agent ID，用于按Agent过滤搜索范围。	my_agent

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v1/agentic-memory/mcp' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "skill_search",
    "arguments": {
      "query": "登录提示",
      "user_id": "your_user_id",
      "limit": 10
    }
  }
}'

响应示例

{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"object\":\"list\",\"query\":\"咖啡\",\"user\":\"your_user_id\",\"scope\":\"user\",\"data\":[{\"rank\":1,\"score\":0.80924644,\"embedding_score\":0.7880516,\"bm25_score\":1.0,\"id\":\"s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166\",\"name\":\"咖啡推荐技能\",\"description\":\"咖啡推荐技能\",\"resource_paths\":[],\"source\":\"user:your_user_id\",\"owner\":\"your_user_id\",\"version\":\"0.1.0\",\"agent_id\":\"\",\"tags\":[\"beverage\",\"coffee\"],\"triggers\":[],\"updated_at\":\"2026-06-02T08:39:21+00:00\",\"metadata\":{\"origin\":\"uploaded\"}}],\"error\":null}"
      }
    ],
    "isError": false
  }
}

skill_view — 获取完整技能

根据Skill ID获取完整技能（含所有文件内容）。

参数

参数	类型	必填	描述	示例值
skill_id	String	是	Skill ID，前缀为`s-`。	s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166
user_id	String	是	用户ID。	your_user_id
file_path	String	否	附件文件路径。指定后返回该附件内容而非SKILL.md主文件。	beans.json

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v1/agentic-memory/mcp' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "skill_view",
    "arguments": {
      "skill_id": "s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166",
      "user_id": "your_user_id"
    }
  }
}'

响应示例

{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"object\":\"skill_view\",\"skill_id\":\"s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166\",\"user_id\":\"your_user_id\",\"agent_id\":\"\",\"name\":\"咖啡推荐技能\",\"version\":\"0.1.0\",\"skill_md\":\"---\\nid: \\\"s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166\\\"\\nname: \\\"咖啡推荐技能\\\"\\ndescription: \\\"咖啡推荐技能\\\"\\nversion: \\\"0.1.0\\\"\\n---\\n\\n# 咖啡推荐技能\\n\\n根据用户偏好推荐咖啡。\\n\",\"linked_files\":{}}"
      }
    ],
    "isError": false
  }
}

skill_manage — 管理Skill

管理技能的全生命周期，包括创建、编辑、补丁修改、删除以及附件文件管理。通过action参数指定操作类型。

参数

参数	类型	必填	描述	示例值
action	String	是	操作类型，取值：`create`（创建技能）、`patch`（文本查找替换）、`edit`（全量编辑）、`delete`（删除技能）、`write_file`（写入附件文件）、`remove_file`（移除附件文件）。	create
user_id	String	是	用户ID。	your_user_id
name	String	条件必填	技能名称（create时必填）。	咖啡推荐技能
skill_id	String	条件必填	Skill ID（create以外的所有action均必填），前缀为`s-`。	s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166
content	String	条件必填	SKILL.md的完整内容，`create`和`edit`时使用。	# 咖啡推荐技能\n\n根据用户偏好推荐咖啡。
old_string	String	条件必填	`patch`时必填，要查找替换的原始文本。	推荐咖啡
new_string	String	条件必填	`patch`时使用，替换后的文本。	推荐精品咖啡
replace_all	Boolean	否	`patch`时使用，是否替换所有匹配项，默认为`false`。	false
tags	Array[String]	否	技能标签列表。	["beverage", "coffee"]
file_path	String	条件必填	附件文件路径。 `write_file`和`remove_file`时必填，`patch`时选填。	beans.json
file_content	String	条件必填	`write_file`时必填，附件文件内容，必须为字符串类型。	{"beans": ["Arabica"]}
absorbed_into	String	否	技能合并目标ID。只在`delete`时必填，该字段会给skill打上标记，不会执行实际逻辑	s-target-skill-id

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v1/agentic-memory/mcp' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "skill_manage",
    "arguments": {
      "action": "create",
      "user_id": "your_user_id",
      "name": "咖啡推荐技能",
      "content": "# 咖啡推荐技能\n\n根据用户偏好推荐咖啡。"
    }
  }
}'

响应示例

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"ok\":true,\"object\":\"skill_create\",\"skill_id\":\"s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166\",\"agent_id\":\"\",\"user_id\":\"your_user_id\",\"name\":\"咖啡推荐技能\",\"version\":\"0.1.0\",\"metadata\":{\"origin\":\"uploaded\"},\"files\":{\"SKILL.md\":\"---\\nid: \\\"s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166\\\"\\nname: \\\"咖啡推荐技能\\\"\\ndescription: \\\"咖啡推荐技能\\\"\\nversion: \\\"0.1.0\\\"\\n---\\n\\n# 咖啡推荐技能\\n\\n根据用户偏好推荐咖啡。\\n\"}}"
      }
    ],
    "isError": false
  }
}

Knowledge Base工具

Knowledge Base工具用于搜索知识库文档与节点内容。使用前需在控制台知识库管理以获取kb_id。所有KB工具均要求kb_id为必填参数。

kb_docs_search — 搜索文档

按描述相关性搜索知识库中的文档。

参数

参数	类型	必填	描述	示例值
query	String	是	搜索关键词。	产品使用手册
kb_id	String	是	知识库ID。	your_kb_id
topk	Int	否	返回文档数上限，默认10。	5

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v1/agentic-memory/mcp' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "kb_docs_search",
    "arguments": {
      "query": "产品使用手册",
      "kb_id": "your_kb_id",
      "topk": 5
    }
  }
}'

响应示例

{
  "jsonrpc": "2.0",
  "id": 11,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"results\":[{\"id\":\"doc-8f3a1c2b\",\"title\":\"产品使用手册\",\"score\":0.91}]}"
      }
    ],
    "isError": false
  }
}

kb_nodes_search — 搜索节点

搜索知识库中的细粒度节点（chunks）。

参数

参数query（String，必填）、kb_id（String，必填）、topk（Int，默认5）、doc_ids（Array[String]，限定搜索范围）、expand（String，节点扩展策略，可选值：max_score（最优父节点扩展）/ cohierarchy（共现层级扩展）/ no_expand（不扩展），默认no_expand）。

说明

当重排后的结果全部来自JSONL数据源时，max_score会自动降级为no_expand。

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v1/agentic-memory/mcp' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "kb_nodes_search",
    "arguments": {
      "query": "如何配置权限",
      "kb_id": "your_kb_id",
      "topk": 3
    }
  }
}'

响应示例

{
  "jsonrpc": "2.0",
  "id": 12,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"results\":[{\"id\":\"node-1a2b3c\",\"doc_id\":\"doc-8f3a1c2b\",\"content\":\"配置权限需在控制台的访问控制页面进行\",\"score\":0.83}]}"
      }
    ],
    "isError": false
  }
}

kb_doc_structure_get — 获取文档目录

获取文档的目录结构（Table of Contents）。参数kb_id（String，必填）、doc_id（String，必填）。

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v1/agentic-memory/mcp' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "kb_doc_structure_get",
    "arguments": {
      "kb_id": "your_kb_id",
      "doc_id": "your_doc_id"
    }
  }
}'

响应示例

{
  "jsonrpc": "2.0",
  "id": 13,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"toc\":[{\"title\":\"第一章 概述\",\"level\":1,\"node_id\":\"node-1a2b3c\"},{\"title\":\"1.1 快速开始\",\"level\":2,\"node_id\":\"node-4d5e6f\"}]}"
      }
    ],
    "isError": false
  }
}

kb_node_content_get — 获取节点内容

根据节点ID列表获取内容。参数node_ids（Array[String]，必填，非空）、kb_id（String，必填）。

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v1/agentic-memory/mcp' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "tools/call",
  "params": {
    "name": "kb_node_content_get",
    "arguments": {
      "node_ids": ["your_node_id_1", "your_node_id_2"],
      "kb_id": "your_kb_id"
    }
  }
}'

响应示例

{
  "jsonrpc": "2.0",
  "id": 14,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"results\":[{\"id\":\"your_node_id_1\",\"content\":\"配置权限需在控制台的访问控制页面进行，支持按角色授权。\"}]}"
      }
    ],
    "isError": false
  }
}

kb_doc_grep — 文档文本搜索

对文档原始文本执行正则或字面量匹配搜索。参数kb_id（String，必填）、doc_id（String，必填）、pattern（String，必填，正则或字面量匹配模式）、context（Int，上下文行数，默认0）、ignore_case（Boolean，默认false）、literal（Boolean，默认false）、limit（Int，最大匹配数，默认100）。

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v1/agentic-memory/mcp' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 15,
  "method": "tools/call",
  "params": {
    "name": "kb_doc_grep",
    "arguments": {
      "kb_id": "your_kb_id",
      "doc_id": "your_doc_id",
      "pattern": "配置.*参数",
      "context": 2,
      "ignore_case": true
    }
  }
}'

响应示例

{
  "jsonrpc": "2.0",
  "id": 15,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"matches\":[{\"line_number\":42,\"line\":\"配置访问参数说明\",\"context\":[\"前一行内容\",\"配置访问参数说明\",\"后一行内容\"]}],\"total\":1}"
      }
    ],
    "isError": false
  }
}

kb_doc_read — 读取文档内容

读取文档的原始文本内容，支持按行分页。参数kb_id（String，必填）、doc_id（String，必填）、offset（Int，起始行号，1-based）、limit（Int，最大返回行数）。

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v1/agentic-memory/mcp' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 16,
  "method": "tools/call",
  "params": {
    "name": "kb_doc_read",
    "arguments": {
      "kb_id": "your_kb_id",
      "doc_id": "your_doc_id",
      "offset": 1,
      "limit": 50
    }
  }
}'

响应示例

{
  "jsonrpc": "2.0",
  "id": 16,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"content\":\"第1行内容\\n第2行内容\\n第3行内容\"}"
      }
    ],
    "isError": false
  }
}

混合检索工具

hybrid_search — 多源并行检索

同时搜索Memory、Skill和Knowledge Base文档，返回按来源分组的结果。各源独立降级，单源失败不影响其他源返回。

参数

参数	类型	必填	描述	示例值
query	String	是	搜索关键词。	如何处理退货
user_id	String	是	用户ID（Memory和Skill搜索范围）。	your_user_id
kb_id	String	否	知识库ID。提供时才搜索KB文档，省略则跳过KB。	your_kb_id
agent_id	String	否	Agent ID（用于Memory过滤）。	your_agent_id
top_k	Int	否	每个源的最大结果数，默认10。	5

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v1/agentic-memory/mcp' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 17,
  "method": "tools/call",
  "params": {
    "name": "hybrid_search",
    "arguments": {
      "query": "如何处理退货",
      "user_id": "your_user_id",
      "kb_id": "your_kb_id",
      "top_k": 5
    }
  }
}'

响应示例

{
  "jsonrpc": "2.0",
  "id": 17,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"query\":\"如何处理退货\",\"memories\":[{\"id\":\"m-xxx\",\"memory\":\"用户上次退货选择了到店退货\",\"score\":0.85}],\"skills\":[{\"id\":\"s-xxx\",\"name\":\"退货流程处理\",\"description\":\"标准退货流程操作指南\"}],\"kb_docs\":[{\"id\":\"doc-xxx\",\"title\":\"退货政策说明\",\"score\":0.91}]}"
      }
    ],
    "isError": false
  }
}