Episodes APIは、エピソード（イベント）を時系列で記録・取得するためのインターフェースです。Q&A履歴、ナレッジの変更履歴、ユーザーアクションなどを追跡できます。
const client = new NdxClient({
apiKey: process.env.NEURADEX_API_KEY,
projectId: 'your-project-id',
});
// Episodes APIにアクセス
const episodes = await client.episodes.list({ timeRange: 'today' });
await client.episodes.create({ ... });
メソッド一覧
| メソッド | 説明 |
|---|
list(options?) | エピソード一覧を取得 |
get(id) | 特定のエピソードを取得 |
create(input) | 新しいエピソードを記録 |
getChildren(id) | 子エピソードを取得 |
getBySession(sessionId) | セッション内のエピソードを取得 |
getRecent(limit?) | 最近のエピソードを取得 |
getToday() | 今日のエピソードを取得 |
getThisWeek() | 今週のエピソードを取得 |
search(query, options?) | エピソードをベクトル検索 |
list()
条件を指定してエピソード一覧を取得します。
パラメータ
時間範囲プリセット: 'today' | 'this_week' | 'this_month'
エピソードタイプでフィルタ: 'question' | 'answer' | 'knowledge_created' など
アクタータイプでフィルタ: 'user' | 'agent' | 'system'
チャネルでフィルタ: 'widget' | 'api' | 'mcp'
戻り値
interface EpisodeListResponse {
data: Episode[];
total: number;
page: number;
limit: number;
}
interface Episode {
id: string;
episodeType: string;
content: string;
actorType: string;
actorId: string | null;
actorName: string | null;
scopeType: string;
scopeId: string;
channel: string | null;
sessionId: string | null;
parentEpisodeId: string | null;
relatedKnowledgeIds: string[];
changeReason: string | null;
previousValue: object | null;
occurredAt: string;
createdAt: string;
}
使用例
// 今日のエピソード
const result = await client.episodes.list({ timeRange: 'today' });
// 特定ユーザーのエピソード
const result = await client.episodes.list({
actorType: 'user',
actorId: 'user-123',
limit: 100,
});
// 日付範囲で取得
const result = await client.episodes.list({
from: '2025-01-01T00:00:00Z',
to: '2025-01-07T23:59:59Z',
});
// 質問エピソードのみ
const result = await client.episodes.list({
episodeType: 'question',
});
get()
特定のエピソードを取得します。
パラメータ
使用例
const episode = await client.episodes.get('episode-123');
console.log(episode.content);
console.log(episode.actorName);
console.log(episode.occurredAt);
create()
新しいエピソードを記録します。
パラメータ
アクタータイプ: 'user' | 'agent' | 'system'
エピソードタイプ: 'question' | 'answer' | 'feedback' など
スコープタイプ: 'project' | 'organization'
チャネル: 'widget' | 'api' | 'mcp'
使用例
// ユーザーの質問を記録
const question = await client.episodes.create({
actorType: 'user',
actorId: 'user-123',
actorName: 'John Doe',
episodeType: 'question',
content: 'パスワードをリセットする方法は？',
scopeType: 'project',
scopeId: 'project-abc',
channel: 'widget',
sessionId: 'session-xyz',
});
// エージェントの回答を記録
const answer = await client.episodes.create({
actorType: 'agent',
actorName: 'Support Bot',
episodeType: 'answer',
content: 'パスワードのリセットは、ログイン画面の「パスワードを忘れた」リンクから行えます。',
scopeType: 'project',
scopeId: 'project-abc',
channel: 'widget',
sessionId: 'session-xyz',
parentEpisodeId: question.id, // 質問に紐付け
relatedKnowledgeIds: ['knowledge-1', 'knowledge-2'],
});
getChildren()
指定したエピソードの子エピソード（返信など）を取得します。
パラメータ
使用例
// 質問に対する回答を取得
const children = await client.episodes.getChildren('question-episode-id');
for (const child of children) {
console.log(`回答: ${child.content}`);
}
getBySession()
セッション内のすべてのエピソードを取得します。会話履歴の取得に便利です。
パラメータ
使用例
// 会話履歴を取得
const result = await client.episodes.getBySession('session-123');
for (const episode of result.data) {
const prefix = episode.episodeType === 'question' ? 'Q' : 'A';
console.log(`${prefix}: ${episode.content}`);
}
getRecent()
最近のエピソードを取得します。
パラメータ
使用例
// 最近10件
const result = await client.episodes.getRecent();
// 最近50件
const result = await client.episodes.getRecent(50);
getToday() / getThisWeek()
今日・今週のエピソードを取得するショートカットメソッドです。
使用例
// 今日のエピソード
const today = await client.episodes.getToday();
// 今週のエピソード
const thisWeek = await client.episodes.getThisWeek();
search()
ベクトル検索でエピソードを検索します。「パスワードリセット」「先週のエラー」など、あいまいなクエリでも関連するエピソードを発見できます。
パラメータ
戻り値
interface EpisodeSearchResponse {
results: EpisodeSearchResult[];
query: string;
}
interface EpisodeSearchResult {
id: string;
episodeType: string;
content: string;
actorType: string;
actorName: string | null;
occurredAt: string;
channel: string | null;
score: number;
}
使用例
// エピソードを検索
const result = await client.episodes.search('パスワードリセット');
for (const episode of result.results) {
console.log(`${episode.actorName}: ${episode.content} (スコア: ${episode.score})`);
}
// 件数を指定
const result = await client.episodes.search('デプロイエラー', { limit: 5 });
エピソードタイプ
| タイプ | 説明 |
|---|
question | ユーザーからの質問 |
answer | エージェントの回答 |
feedback | ユーザーのフィードバック |
knowledge_created | ナレッジの作成 |
knowledge_updated | ナレッジの更新 |
knowledge_deleted | ナレッジの削除 |
search | 検索の実行 |
ユースケース
会話履歴の保存
async function recordConversation(
sessionId: string,
question: string,
answer: string,
userId: string,
) {
// 質問を記録
const questionEpisode = await client.episodes.create({
actorType: 'user',
actorId: userId,
episodeType: 'question',
content: question,
scopeType: 'project',
scopeId: projectId,
channel: 'api',
sessionId,
});
// 回答を記録
await client.episodes.create({
actorType: 'agent',
actorName: 'Assistant',
episodeType: 'answer',
content: answer,
scopeType: 'project',
scopeId: projectId,
channel: 'api',
sessionId,
parentEpisodeId: questionEpisode.id,
});
}
アクティビティダッシュボード
async function getActivityStats() {
const today = await client.episodes.getToday();
const stats = {
questions: today.data.filter(e => e.episodeType === 'question').length,
answers: today.data.filter(e => e.episodeType === 'answer').length,
uniqueUsers: new Set(
today.data
.filter(e => e.actorType === 'user')
.map(e => e.actorId)
).size,
};
console.log(`今日の質問数: ${stats.questions}`);
console.log(`今日の回答数: ${stats.answers}`);
console.log(`ユニークユーザー: ${stats.uniqueUsers}`);
return stats;
}
次のステップ
