通过API调用Agentic Memory智能体记忆服务

公共URI

Memory 接口（V4）：

{host}/v4/openapi/workspaces/{workspace_name}/memory/{service_id}

Skill / Knowledge Base / 健康检查接口（V3）：

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}

参数说明：

• host：调用服务的地址，支持通过公网和VPC两种方式调用API服务，可参见获取服务接入地址。

• workspace_name：工作空间名称，例如default。

• service_id：服务ID，固定值为agentic-memory。

Header参数

API-KEY认证

存储 Memory

从消息内容中智能提取用户偏好信息并存储为 Memory。存储过程为异步处理，接口返回事件 ID（event_id），可通过查询任务状态接口获取处理结果。系统会自动搜索已有记忆并去重，自动判断新增或更新。

请求方式

POST

URL

{host}/v4/openapi/workspaces/{workspace_name}/memory/{service_id}/memories/add

Body参数

返回参数

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v4/openapi/workspaces/default/memory/agentic-memory/memories/add' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "messages": [
    {"role": "user", "content": "我喜欢喝咖啡，帮我推荐"},
    {"role": "assistant", "content": "为您推荐美式咖啡..."}
  ],
  "user_id": "user_123",
  "metadata": {"source": "example"}
}'

响应示例

{
  "message": "Memory creation accepted; poll the event endpoint for status.",
  "status": "PENDING",
  "event_id": "me-06bde8b5-d123-43cf-9898-64d08fbfaafc"
}

查询事件状态

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

请求方式

GET

URL

{host}/v4/openapi/workspaces/{workspace_name}/memory/{service_id}/events/{event_id}

Path参数

返回参数

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v4/openapi/workspaces/default/memory/agentic-memory/events/me-06bde8b5-d123-43cf-9898-64d08fbfaafc' \
--header 'Authorization: Bearer 您的API-KEY'

响应示例

{
  "id": "me-06bde8b5-d123-43cf-9898-64d08fbfaafc",
  "status": "SUCCEEDED",
  "results": [
    "m-8d0417d7-9368-4777-9016-b7ee6daeb70b",
    "m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04"
  ]
}

搜索 Memory

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

请求方式

POST

URL

{host}/v4/openapi/workspaces/{workspace_name}/memory/{service_id}/memories/search

Body参数

{
  "AND": [
    {
      "user_id": "user_123"
    },
    {
      "agent_id": "agent_123"
    }
  ]
}

返回参数

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v4/openapi/workspaces/default/memory/agentic-memory/memories/search' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "query": "咖啡",
  "filters": {"AND": [{"user_id": "user_123"}]},
  "top_k": 10
}'

响应示例

{
  "results": [
      {
        "id": "m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04",
        "memory": "助手为用户推荐了美式咖啡",
        "score": 0.9151,
        "metadata": {"source": "example"},
        "created_at": "2026-06-02T08:39:21.482047Z",
        "updated_at": "2026-06-02T08:39:21.482047Z"
      }
    ]
  }
}

获取 Memory

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

请求方式

GET

URL

{host}/v4/openapi/workspaces/{workspace_name}/memory/{service_id}/memories/{memory_id}

Path参数

返回参数

响应包含 id、memory、user_id、agent_id、run_id、metadata、created_at、updated_at 等字段，字段定义与搜索 Memory响应中的单条记录一致。

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v4/openapi/workspaces/default/memory/agentic-memory/memories/m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04' \
--header 'Authorization: Bearer 您的API-KEY'

响应示例

{
  "id": "m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04",
  "memory": "助手为用户推荐了美式咖啡",
  "user_id": "user_123",
  "agent_id": "agent_001",
  "run_id": "run_001",
  "metadata": {"source": "example"},
  "created_at": "2026-06-02T08:39:21.482047Z",
  "updated_at": "2026-06-02T08:39:21.482047Z"
}

更新 Memory

根据 Memory ID 更新已有记忆内容或附加 metadata。

请求方式

PUT

URL

{host}/v4/openapi/workspaces/{workspace_name}/memory/{service_id}/memories/{memory_id}

Body参数

Curl请求示例

curl --location --request PUT 'http://****-hangzhou.opensearch.aliyuncs.com/v4/openapi/workspaces/default/memory/agentic-memory/memories/m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "text": "助手为用户推荐了拿铁咖啡",
  "metadata": {"category": "updated"}
}'

响应示例

{
  "id": "m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04",
  "text": "助手为用户推荐了拿铁咖啡",
  "user_id": "user_123",
  "agent_id": "agent_001",
  "run_id": "run_001",
  "metadata": {"source": "example", "category": "updated"},
  "created_at": "2026-06-02T08:39:21.482047Z",
  "updated_at": "2026-06-02T08:40:18.428159Z"
}

删除 Memory

根据 Memory ID 删除一条 Memory。返回 message 指示删除结果。

请求方式

DELETE

URL

{host}/v4/openapi/workspaces/{workspace_name}/memory/{service_id}/memories/{memory_id}

Curl请求示例

curl --location --request DELETE 'http://****-hangzhou.opensearch.aliyuncs.com/v4/openapi/workspaces/default/memory/agentic-memory/memories/m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04' \
--header 'Authorization: Bearer 您的API-KEY'

响应示例

{
  "message": "Memory m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04 deleted successfully"
}

提取并存储 Skill

从多轮对话中智能提取可复用技能（Skill）并存储。处理为异步任务，接口返回任务 ID，可通过查询 Skill 任务状态接口获取结果。

请求方式

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/skills/add

Body参数

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/skills/add' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "messages": [
    {"role": "user", "content": "统一登录失败提示文案"},
    {"role": "assistant", "content": "将三端登录失败统一为登录信息有误，请重试"}
  ],
  "user_id": "user_123"
}'

响应示例

{
  "request_id": "3bb081b08c7e4fc8516d26f647f0b2bc",
  "latency": 1659,
  "status": "OK",
  "result": {
    "task_id": "st-73a7c2f1-5600-435e-a4a2-7a9dff6186cf"
  }
}

上传 Skill（ZIP 包导入）

通过 ZIP 包方式上传 Skill。每个 ZIP 包只能包含一个 Skill。返回导入成功的 Skill 数量与元信息列表。

请求方式

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/skills/import

Body参数

返回参数

Curl请求示例

curl -X POST --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/skills/import' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "zip_base64": "<base64编码的ZIP文件内容>",
  "user_id": "user_123",
  "overwrite_same_name": false
}'

响应示例

{
  "request_id": "18d236243f851d13c6fd456743fbec8a",
  "latency": 246,
  "status": "OK",
  "result": {
    "imported_count": 1,
    "data": [
      {
        "id": "s-8f9ac898-820b-4ac5-b981-88c7a7f0edae",
        "name": "上传测试技能",
        "description": "通过 doctest 验证上传 Skill 接口的响应字段结构",
        "version": "0.2.0",
        "owner": "user_123",
        "tags": ["test", "doc"],
        "triggers": ["测试上传", "verify upload"],
        "resource_paths": ["_meta.json", "scripts/echo.py", "references/notes.md"],
        "updated_at": "2026-06-02T09:17:57+00:00"
      }
    ]
  }
}

查询 Skill 任务状态

查询提取/存储 Skill 的异步任务处理状态及生成的 Skill ID 列表。

请求方式

GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/skills/tasks/{task_id}

返回参数

响应包含 result.task_id、result.status（pending/running/completed/failed）、result.skill_ids（生成的 Skill ID 列表）、result.error_message。

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/skills/tasks/st-73a7c2f1-5600-435e-a4a2-7a9dff6186cf' \
--header 'Authorization: Bearer 您的API-KEY'

响应示例

{
  "request_id": "2c941feb3468ff5d6ef229204734cddb",
  "latency": 3,
  "status": "OK",
  "result": {
    "task_id": "st-73a7c2f1-5600-435e-a4a2-7a9dff6186cf",
    "status": "completed",
    "skill_ids": ["s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166"]
  }
}

搜索 Skill

根据查询条件搜索 Skill。Body 参数 query 与 user_id 必填，agent_id、size（默认 10）可选；响应 result.results[] 含 skill_id、name、description、version、user_id、agent_id。

请求方式

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/skills/search

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/skills/search' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "query": "登录提示",
  "user_id": "user_123",
  "size": 10
}'

响应示例

{
  "request_id": "74b5ab4d470e4b7a7811b1b6e7d79c07",
  "latency": 142,
  "status": "OK",
  "result": {
    "results": [
      {
        "skill_id": "s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166",
        "name": "测试技能",
        "description": "文档测试用技能",
        "version": "0.1.0",
        "user_id": "user_123"
      }
    ]
  }
}

获取 Skill

根据 Skill ID 获取单条 Skill 详情，包含 SKILL.md 等文件内容。响应包含 result.skill_id、result.name、result.version、result.files、result.user_id、result.agent_id。

请求方式

GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/skills/{skill_id}

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/skills/s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166' \
--header 'Authorization: Bearer 您的API-KEY'

响应示例

{
  "request_id": "6d46c81b462f5ec93b94281d5be1ca3a",
  "latency": 89,
  "status": "OK",
  "result": {
    "skill_id": "s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166",
    "name": "测试技能",
    "version": "0.1.0",
    "files": {
      "SKILL.md": "---\nid: \"s-c0e6aaf9-...\"\nname: \"测试技能\"\nversion: \"0.1.0\"\n---\n# 测试技能"
    },
    "user_id": "user_123",
    "agent_id": ""
  }
}

更新 Skill

更新指定 Skill 的信息，可单独更新一个或多个字段。Body 中 user_id 必填，其余字段（name、version、files、agent_id、description、tags）按需传入。响应结构与获取 Skill 一致。

请求方式

PUT

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/skills/{skill_id}

Curl请求示例

curl -X PUT --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/skills/s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "version": "1.0",
  "user_id": "user_123"
}'

响应示例

{
  "request_id": "224c2313-7b70-47f7-8748-8f583d7b9ae1",
  "latency": 284,
  "status": "OK",
  "result": {
    "name": "统一多端登录失败提示文案",
    "version": "1.0",
    "files": {
      "SKILL.md": "---\nid: \"s-c0e6aaf9-...\"\nname: \"统一多端登录失败提示文案\"\n..."
    }
  }
}

删除 Skill

根据 Skill ID 删除一条 Skill。响应包含 result.skill_id、result.status、result.message。

请求方式

DELETE

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/skills/{skill_id}

Curl请求示例

curl --location --request DELETE 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/skills/s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166' \
--header 'Authorization: Bearer 您的API-KEY'

响应示例

{
  "request_id": "477bdd93f61dfb229452febd6f7d1725",
  "latency": 181,
  "status": "OK",
  "result": {
    "skill_id": "s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166",
    "status": "success",
    "message": "Skill s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166 deleted"
  }
}

上传 KB 文档

向知识库上传文档，支持 LOCAL（本地文件 URL）和 OSS 两种来源。

请求方式

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/knowledge-bases/{kb_id}/docs

Body参数

返回参数

响应包含 id（上传成功后生成的文档 ID）和 result.error_message（失败时不为空）。

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/knowledge-bases/kb-001/docs' \
--header 'Authorization: Bearer 您的API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "type": "LOCAL",
  "doc": {
    "id": "doc-001",
    "title": "使用手册",
    "file_url": "https://example.com/manual.pdf"
  }
}'

获取 KB 文档列表

分页获取知识库下的文档列表。Query 参数 page_number（默认 1）和 page_size（默认 10，最大 100）可选。响应 result.results[] 含 id、title、timestamp、status（PROCESSING / SUCCESS / FAIL），result.total 为总数。

请求方式

GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/knowledge-bases/{kb_id}/docs

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/knowledge-bases/kb-001/docs?page_number=1&page_size=10' \
--header 'Authorization: Bearer 您的API-KEY'

查看 KB 文档详情

根据文档 ID 获取知识库文档详情。响应 result 包含 id、title、content、status、timestamp 字段。

请求方式

GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/knowledge-bases/{kb_id}/docs/{doc_id}

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/knowledge-bases/kb-001/docs/doc-001' \
--header 'Authorization: Bearer 您的API-KEY'

删除 KB 文档

根据文档 ID 删除知识库文档。响应 result 包含 id（被删除的文档 ID）和 error_message（失败时不为空）。

请求方式

DELETE

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/knowledge-bases/{kb_id}/docs/{doc_id}

Curl请求示例

curl --location --request DELETE 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/knowledge-bases/kb-001/docs/doc-001' \
--header 'Authorization: Bearer 您的API-KEY'

健康检查

检查 Memory 服务的健康状态。该接口位于服务状态分类，URI 沿用 V3 前缀（V4 路径下没有 health endpoint）。

请求方式

GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/health

返回参数

Curl请求示例

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/health' \
--header 'Authorization: Bearer 您的API-KEY'

响应示例

{
  "request_id": "287d9462-3c9a-2706-780e-b49aa3702e01",
  "latency": 6,
  "status": "OK",
  "result": {
    "status": "healthy"
  }
}

异常响应示例

{
  "request_id": "590A7EB8-AA84-****-AF31-8C35DC965972",
  "latency": 0,
  "code": "InvalidParameter",
  "http_code": 400,
  "message": "user_id is required"
}