Agent Storage SDK - Tablestore

AI Agent 情境需要長期記憶與知識檢索能力。Tablestore Agent Storage SDK 是面向 AI Agent 情境的專用 SDK，統一封裝記憶庫（Memory Store）與知識庫（Knowledge Base）介面，提供 Python 與 TypeScript 兩種語言版本。相比通用的Table Store SDK，Agent Storage SDK 支援 API Key 認證，接入更簡單。

與 Tablestore SDK 的區別

Agent Storage SDK 是 Tablestore SDK 之外的獨立 SDK，專註於 Agent 儲存情境。兩者主要差異如下。

維度	Tablestore SDK	Agent Storage SDK
包名	Python：`tablestore`；Node.js：`tablestore`	Python：`tablestore-agent-storage`；TypeScript：`@tablestore/agent-storage`
用戶端類	`OTSClient` / `AsyncOTSClient` / `TableStore.Client`	`AgentStorageClient`
覆蓋能力	Table Store全量介面，含記憶庫介面	僅 Agent 儲存介面（記憶庫 + 知識庫）
認證方式	AccessKey（AK/SK）	API Key 或 AccessKey（AK/SK）

安裝和配置

前提條件

已開通Table Store服務並建立執行個體，擷取執行個體的 HTTPS Endpoint 與執行個體名。
若使用 API Key 認證：已在目標執行個體上建立 API Key，並為 API Key 綁定的 RAM 子帳號授予 ots:CallWithBearerToken 許可權。API Key 的介面許可權繼承該子帳號的 RAM 策略。
若使用知識庫能力：已開通阿里雲Object Storage Service 並建立 Bucket，用於儲存原始文檔。上傳文檔時 SDK 需要 OSS 訪問憑證（AccessKey），初始化用戶端時需額外傳入 oss_endpoint 和 oss_bucket 參數。

安裝

按語言選擇對應的包。

Python

pip install tablestore-agent-storage

TypeScript/Node.js

npm install @tablestore/agent-storage

認證方式

Agent Storage SDK 支援兩種認證方式，對比如下。

認證方式	適用情境	支援介面	傳輸要求
AccessKey（AK/SK）	全功能訪問，含表格管理與資料操作	Table Store全部介面	HTTP / HTTPS
API Key	AI 情境輕量接入，免管理 AccessKey ID/Secret	僅記憶庫、知識庫服務介面	強制 HTTPS

API Key 的建立與授權流程詳見 API Key 管理。

初始化用戶端

推薦使用 API Key 認證；如需知識庫上傳或其他Table Store介面，需同時提供 AccessKey 與 OSS 配置。

使用 API Key 訪問（推薦）

通過 api_key 參數和執行個體資訊初始化用戶端，端點必須為 HTTPS。

Python

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

resp = client.list_memory_stores({})
for store in resp["stores"]:
    print(store["memoryStoreName"])

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const resp = await client.listMemoryStores({});
for (const store of resp.stores) {
  console.log(store.memoryStoreName);
}

cURL

API Key 通過 x-ots-apikey 要求標頭傳遞。

curl -X POST 'https://<instance>.<region>.ots.aliyuncs.com/ListMemoryStores' \
  -H 'x-ots-instancename: <instance-name>' \
  -H 'x-ots-apikey: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{}'

使用 AccessKey 訪問

訪問Table Store完整介面或上傳知識庫文檔（涉及 OSS）時，使用 AccessKey 認證。

Python

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    access_key_id="<AccessKey ID>",
    access_key_secret="<AccessKey Secret>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
    # 若使用知識庫能力，需同時配置 OSS
    oss_endpoint="https://oss-<region>.aliyuncs.com",
    oss_bucket_name="<bucket-name>",
)

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
  accessKeyId: process.env.OTS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OTS_ACCESS_KEY_SECRET,
});

記憶庫操作樣本

記憶庫（Memory Store）用於持久化 AI Agent 的多輪對話記憶，並支援基於向量的語義檢索。SDK 方法與 REST API 一一對應，Python 使用 snake_case，TypeScript 使用 camelCase，入參與介面一致。

Python

# 1. 建立記憶庫
client.create_memory_store({
    "memoryStoreName": "agent_memory",
    "description": "Agent 長期記憶庫",
    "extractInstructions": "重點關注使用者的飲食偏好與出行習慣",
})

# 2. 寫入記憶
client.add_memories({
    "memoryStoreName": "agent_memory",
    "scope": {
        "appId": "app-001",
        "tenantId": "user-001",
        "agentId": "assistant",
        "runId": "session-001",
    },
    "messages": [
        {"role": "user", "content": "我喜歡喝美式咖啡"},
    ],
    "sync": True,
})

# 3. 檢索記憶
result = client.search_memories({
    "memoryStoreName": "agent_memory",
    "scope": {
        "appId": "app-001",
        "tenantId": "user-001",
        "agentId": "*",
        "runId": "*",
    },
    "query": "使用者喜歡什麼飲品",
    "topK": 5,
    "includeEvidence": True,
    "minSimilarity": 0.3,
})
for hit in result["data"]["memories"]:
    print(hit["content"], hit["similarity"])

# 4. 列出記憶庫
resp = client.list_memory_stores({})
for store in resp["stores"]:
    print(store["memoryStoreName"])

TypeScript

// 1. 建立記憶庫
await client.createMemoryStore({
  memoryStoreName: 'agent_memory',
  description: 'Agent 長期記憶庫',
});

// 2. 寫入記憶
await client.addMemories({
  memoryStoreName: 'agent_memory',
  scope: {
    appId: 'app-001',
    tenantId: 'user-001',
    agentId: 'assistant',
    runId: 'session-001',
  },
  messages: [{ role: 'user', content: '我喜歡喝美式咖啡' }],
  sync: true,
});

// 3. 檢索記憶
const result = await client.searchMemories({
  memoryStoreName: 'agent_memory',
  scope: { appId: 'app-001', tenantId: 'user-001', agentId: '*', runId: '*' },
  query: '使用者喜歡什麼飲品',
  topK: 5,
  includeEvidence: true,
});
for (const hit of result.data.memories) {
  console.log(hit.content, hit.similarity);
}

除上述樣本外，SDK 還提供更新記憶庫、刪除記憶庫、按 Scope 列出記憶、擷取單條記憶、非同步任務查詢等方法。完整介面清單與參數說明詳見記憶儲存 API 介面介紹。

知識庫操作樣本

知識庫（Knowledge Base）支援文檔自動切片、向量化與混合檢索，適合企業問答、RAG 等情境。文檔源檔案儲存體在 OSS，切片索引與檢索由Table Store完成，使用前需同時配置 OSS 與Table Store。

建立知識庫時如果不顯式指定向量模型，SDK 使用阿里雲百鍊 text-embedding-v4 模型（1024 維），預設檢索方式為向量檢索與全文檢索索引的混合檢索。

Python

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    access_key_id="<AccessKey ID>",
    access_key_secret="<AccessKey Secret>",
    oss_endpoint="https://oss-<region>.aliyuncs.com",
    oss_bucket_name="<bucket-name>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

# 1. 建立知識庫（預設使用百鍊 text-embedding-v4 向量模型，
#    預設檢索方式為向量檢索 + 全文檢索索引的混合檢索）
client.create_knowledge_base({
    "knowledgeBaseName": "product_kb",
    "description": "產品知識庫",
})

# 2. 上傳本地文檔（SDK 會先將檔案上傳至 OSS，再觸發切片與向量化）
client.upload_documents({
    "knowledgeBaseName": "product_kb",
    "documents": [
        {
            "documentId": "doc-guide-001",
            "filePath": "./docs/product-overview.txt",
        },
        {
            "documentId": "doc-guide-002",
            "filePath": "./docs/sdk-intro.txt",
        },
    ],
})

# 3. 列出知識庫中的文檔
resp = client.list_documents({
    "knowledgeBaseName": "product_kb",
    "maxResults": 10,
})
for doc in resp["data"]["documentDetails"]:
    print(doc.get("documentId"), doc.get("ossKey"), doc.get("status"))

# 4. 檢索
from tablestore_agent_storage.models import RetrieveRequest, RetrievalQuery

req = RetrieveRequest(
    knowledge_base_name="product_kb",
    retrieval_query=RetrievalQuery(text="Agent Storage SDK 有什麼用"),
)
result = client.retrieve(req)
for hit in result["data"]["retrievalResults"]:
    print(hit)

# 5. 刪除文檔
client.delete_documents({
    "knowledgeBaseName": "product_kb",
    "documents": [{"documentId": "doc-guide-001"}],
})

# 6. 刪除知識庫
client.delete_knowledge_base({"knowledgeBaseName": "product_kb"})

TypeScript

import { NodeAgentStorageClient } from '@tablestore/agent-storage/node';

const client = new NodeAgentStorageClient({
  accessKeyId: '<AccessKey ID>',
  accessKeySecret: '<AccessKey Secret>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
  ossEndpoint: 'https://oss-<region>.aliyuncs.com',
  ossBucketName: '<bucket-name>',
  ossAccessKeyId: '<AccessKey ID>',
  ossAccessKeySecret: '<AccessKey Secret>',
});

// 1. 建立知識庫（預設使用百鍊 text-embedding-v4 向量模型，
//    預設檢索方式為向量檢索 + 全文檢索索引的混合檢索）
await client.createKnowledgeBase({
  knowledgeBaseName: 'product_kb',
  description: '產品知識庫',
});

// 2. 上傳本地文檔（SDK 會先將檔案上傳至 OSS，再觸發切片與向量化）
//    TypeScript SDK 在上傳時由服務端自動產生 docId，不接受自訂 documentId
await client.uploadDocuments({
  knowledgeBaseName: 'product_kb',
  documents: [
    { filePath: './docs/product-overview.txt' },
    { filePath: './docs/sdk-intro.txt' },
  ],
});

// 3. 列出知識庫中的文檔
const resp = await client.listDocuments({
  knowledgeBaseName: 'product_kb',
  maxResults: 10,
});
for (const doc of resp.data.documentDetails) {
  console.log(doc.docId, doc.ossKey, doc.status);
}

// 4. 檢索
const result = await client.retrieve({
  knowledgeBaseName: 'product_kb',
  retrievalQuery: { text: 'Agent Storage SDK 有什麼用' },
});
for (const hit of result.data.retrievalResults) {
  console.log(hit);
}

// 5. 刪除文檔（TypeScript 需要通過上一步返回的 ossKey 指定要刪除的文檔）
await client.deleteDocuments({
  knowledgeBaseName: 'product_kb',
  documents: [{ ossKey: '<oss-key-from-list>' }],
});

// 6. 刪除知識庫
await client.deleteKnowledgeBase({ knowledgeBaseName: 'product_kb' });

上傳文檔後，切片與向量化非同步執行，通常數十秒到數分鐘完成。可通過 list_documents（TypeScript 為 listDocuments）查詢文檔 status 欄位確認索引進度。