OpenSearch：通過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。返回匯入成功的 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"
}'

響應樣本

{
  "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"
}