Tablestore:クイックスタート

前提条件

開始する前に、次のものが準備できていることを確認してください：

• 中国 (北京) リージョンにある Tablestore インスタンス。Tablestore エージェントメモリは現在このリージョンでのみ利用可能です。

• AccessKey 認証情報 (AccessKey ID と AccessKey Secret)、または API キー (API キーの作成については、「API キーの管理」をご参照ください)。

CLI ダッシュボードの使用

tablestore-agent-cli コマンドラインツールには、Next.js ベースの Web ダッシュボードが組み込まれています。ダッシュボードを使用して、認証情報の設定、メモリストアの管理、メモリの書き込みや検索をテストできます。コードは不要です。

1. CLI をインストールします (Node.js 18 以降が必要です)：

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

2. ダッシュボードを起動します。デフォルトでは 127.0.0.1:3000 でリッスンします。

   tablestore-agent-cli dashboard start

3. ブラウザで http://127.0.0.1:3000 を開き、ダッシュボードで次の手順を完了します：

   • Tablestore のアクセス認証情報 (AccessKey ペアまたは API キー) を設定します。

   • メモリストアを作成し、メモリを追加して、セマンティック検索を実行します。

コマンドライン操作、およびスコープの隔離、Dream を使用したメモリ統合、監査クエリなどの高度な機能については、「エージェントストレージ CLI」と「メモリストア操作」をご参照ください。

エージェントストレージ SDK の使用

エージェントストレージ SDK は、Python と TypeScript で利用できます。API キーで認証するため、AccessKey ペアを管理する必要はありません。

pip install tablestore-agent-storage

from tablestore_agent_storage import AgentStorageClient

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

scope = {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001",
}

# 1. メモリストアを作成します
client.create_memory_store({"memoryStoreName": "agent_memory"})

# 2. メモリを追加します
client.add_memories({
    "memoryStoreName": "agent_memory",
    "scope": scope,
    "text": "The user enjoys coffee and prefers concise responses.", # ユーザーはコーヒーを好み、簡潔な応答を好みます。
    "sync": True,
})

# 3. セマンティック検索を実行します
result = client.search_memories({
    "memoryStoreName": "agent_memory",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "*", "runId": "*"},
    "query": "What beverages does the user like?", # ユーザーはどの飲み物が好きですか？
    "topK": 5,
})
for item in result.get("results", []):
    unit = item["unit"]
    print(f"[{item['score']:.4f}] {unit['text']}")

npm install @tablestore/agent-storage

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

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

const scope = {
  appId: 'app-001',
  tenantId: 'user-001',
  agentId: 'assistant',
  runId: 'session-001',
};

// 1. メモリストアを作成します
await client.createMemoryStore({ memoryStoreName: 'agent_memory' });

// 2. メモリを追加します
await client.addMemories({
  memoryStoreName: 'agent_memory',
  scope,
  text: 'The user enjoys coffee and prefers concise responses.', // ユーザーはコーヒーを好み、簡潔な応答を好みます。
  sync: true,
});

// 3. セマンティック検索を実行します
const result: any = await client.searchMemories({
  memoryStoreName: 'agent_memory',
  scope: { appId: 'app-001', tenantId: 'user-001', agentId: '*', runId: '*' },
  query: 'What beverages does the user like?', // ユーザーはどの飲み物が好きですか？
  topK: 5,
});
for (const item of result.results ?? []) {
  console.log(`[${item.score.toFixed(4)}] ${item.unit.text}`);
}

スコープの隔離、Rerank による再ランキング、Dream を使用したメモリ統合、非同期タスクなど、SDK の詳細な使用方法については、「エージェントストレージ SDK」をご参照ください。

Tablestore ネイティブ SDK の使用

Tablestore ネイティブ SDK は、Python と Node.js で利用できます。これを使用して、既存の Tablestore アプリケーションに長期記憶を追加できます。ネイティブ SDK は現在、AccessKey 認証のみをサポートしています。

pip install "tablestore>=6.4.7"

from tablestore import OTSClient

client = OTSClient(
    "https://<instance>.cn-beijing.ots.aliyuncs.com",
    "<AccessKey ID>",
    "<AccessKey Secret>",
    "<instance-name>",
)

scope = {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001",
}

# 1. メモリストアを作成します
client.create_memory_store({"memoryStoreName": "agent_memory"})

# 2. メモリを追加します
client.add_memories({
    "memoryStoreName": "agent_memory",
    "scope": scope,
    "text": "The user enjoys coffee and prefers concise responses.", # ユーザーはコーヒーを好み、簡潔な応答を好みます。
    "sync": True,
})

# 3. セマンティック検索を実行します
result = client.search_memories({
    "memoryStoreName": "agent_memory",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "*", "runId": "*"},
    "query": "What beverages does the user like?", # ユーザーはどの飲み物が好きですか？
    "topK": 5,
})
for item in result.get("results", []):
    unit = item["unit"]
    print(f"[{item['score']:.4f}] {unit['text']}")

npm install tablestore@^5.6.5

const TableStore = require("tablestore");

const client = new TableStore.Client({
  accessKeyId: "<AccessKey ID>",
  secretAccessKey: "<AccessKey Secret>",
  endpoint: "https://<instance>.cn-beijing.ots.aliyuncs.com",
  instanceName: "<instance-name>",
});

const scope = {
  appId: "app-001",
  tenantId: "user-001",
  agentId: "assistant",
  runId: "session-001",
};

// 1. メモリストアを作成します
await client.createMemoryStore({ memoryStoreName: "agent_memory" });

// 2. メモリを追加します
await client.addMemories({
  memoryStoreName: "agent_memory",
  scope,
  text: "The user enjoys coffee and prefers concise responses.", // ユーザーはコーヒーを好み、簡潔な応答を好みます。
  sync: true,
});

// 3. セマンティック検索を実行します
const result = await client.searchMemories({
  memoryStoreName: "agent_memory",
  scope: { appId: "app-001", "tenantId": "user-001", agentId: "*", runId: "*" },
  query: "What beverages does the user like?", // ユーザーはどの飲み物が好きですか？
  topK: 5,
});
for (const item of result.results ?? []) {
  console.log(`[${item.score.toFixed(4)}] ${item.unit.text}`);
}

ネイティブ SDK の詳細な使用方法については、「Python SDK」と「Node.js SDK」をご参照ください。

AI エージェントフレームワークの使用

OpenClaw や Hermes などの AI エージェントフレームワークに長期記憶を追加するには、そのフレームワーク用のプラグインをインストールしてください。このプラグインを使用すると、エージェントは SDK コードを記述することなく、メモリストアから直接読み書きできます。

各フレームワークの統合手順については、「エージェントエコシステムとの統合」をご参照ください。