Tablestore:Quick start

Prerequisites

Before you begin, make sure that you have:

• An activated Tablestore instance in a supported region

  Note

  Knowledge Storage is currently available in China (Beijing), China (Shanghai), China (Hangzhou), China (Shenzhen), China (Hong Kong), and Singapore.

• An OSS bucket for source documents

  Note

  The OSS bucket must be in the same region as the Tablestore instance.

• OSS access granted to the Knowledge Storage service. If not yet granted, use the one-click authorization link to authorize it.

• AccessKey credentials (AccessKey ID and AccessKey Secret) for accessing Tablestore and OSS

Use the built-in Dashboard

Use the built-in Dashboard in tablestore-agent-cli to configure credentials, manage knowledge bases, upload documents, and run retrievals — no coding required.

1. Install the CLI. Node.js 18 or later is required.

   npm install -g @tablestore/tablestore-agent-cli --registry=https://registry.npmjs.org/

2. Start the Dashboard.

   tablestore-agent-cli dashboard start

3. Open http://127.0.0.1:3000 in your browser and complete the following in the Dashboard:

   • Configure access credentials for Tablestore and OSS.

   • Create a knowledge base, upload local documents, and run a retrieval.

For CLI-based workflows or advanced capabilities — such as instance management, batch operations, and custom embedding models — see Agent Storage CLI and Knowledge base operations.

Use the Agent Storage SDK

The Agent Storage SDK is available in Python and TypeScript. The following examples show a four-step workflow: create a knowledge base, upload documents, wait for indexing to complete, and run a retrieval.

pip install tablestore-agent-storage

from tablestore_agent_storage import AgentStorageClient
import time

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_endpoint="https://oss-<region>.aliyuncs.com",
    oss_bucket_name="<bucket-name>",
)

# 1. Create a knowledge base (defaults to Bailian text-embedding-v4 embedding model with hybrid retrieval combining vector search and full-text search)
client.create_knowledge_base({"knowledgeBaseName": "product_docs_kb"})

# 2. Upload a local document
resp = client.upload_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [{"filePath": "/path/to/file.pdf"}],
})
doc_id = resp["data"]["documentDetails"][0]["docId"]

# 3. Poll until indexing is complete
while True:
    data = client.get_document({"knowledgeBaseName": "product_docs_kb", "docId": doc_id}).get("data") or []
    if data and data[0]["status"] == "completed":
        break
    time.sleep(5)

# 4. Perform retrieval
results = client.retrieve({
    "knowledgeBaseName": "product_docs_kb",
    "retrievalQuery": {"type": "TEXT", "text": "What are the installation steps for the product"},
})
for r in results["data"]["retrievalResults"]:
    print(f"[{r['score']:.4f}] {r['content'][:80]}")

npm install @tablestore/agent-storage

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. Create a knowledge base
await client.createKnowledgeBase({ knowledgeBaseName: 'product_docs_kb' });

// 2. Upload a local document
const resp = await client.uploadDocuments({
  knowledgeBaseName: 'product_docs_kb',
  documents: [{ filePath: '/path/to/file.pdf' }],
});
const docId = resp.data.documentDetails[0].docId;

// 3. Poll until indexing is complete
while (true) {
  const { data } = await client.getDocument({ knowledgeBaseName: 'product_docs_kb', docId });
  if (data && data[0].status === 'completed') break;
  await new Promise((r) => setTimeout(r, 5000));
}

// 4. Perform retrieval
const results = await client.retrieve({
  knowledgeBaseName: 'product_docs_kb',
  retrievalQuery: { type: 'TEXT', text: 'What are the installation steps for the product' },
});
for (const r of results.data.retrievalResults) {
  console.log(`[${r.score.toFixed(4)}] ${r.content.slice(0, 80)}`);
}

For more information about the SDK — including metadata filtering, reranking, chunk-level management, and custom embedding models — see Agent Storage SDK.

Integrate with AI agent frameworks

To integrate Knowledge Storage with AI agent frameworks such as Hermes, OpenClaw, and Claude Code, install the skill integrations provided by tablestore-agent-cli. Your agent can then call the knowledge base directly to perform retrieval, write, and management operations — no SDK code required.

For detailed integration steps, see AI agent integrations.