ナレッジベース

AIエージェントにライブで検索可能なブレインを提供します。ドキュメントをアップロードするかAPI経由でデータをプッシュすると、ナレッジベースがエージェントが会話中にクエリできるナレッジグラフを自動構築します。

概要

ナレッジベースは、データを構造化されたナレッジグラフに変換するドメイン非依存のシステムです。AIエージェントは会話中にこのグラフを検索し、ハルシネーションの代わりに正確で根拠のある応答を提供します。

Upload document / API push
       |
       v
Extract entities + relationships
       |
       v
Build knowledge graph (deduplicated nodes + edges)
       |
       v
Run analytics rules (recommendations, trends)
       |
       v
Agent queries graph during conversations

データ取り込みの2つの方法

1. ドキュメントアップロード

PDF、DOCX、Markdown、プレーンテキストファイルをアップロードします。プラットフォームがドキュメントを自動処理し、エンティティと関係を抽出してナレッジグラフに追加します。

import fs from "fs";

const doc = await client.knowledge.uploadDocument(projectId, {
  file: fs.createReadStream("product_catalog.pdf"),
  fileName: "product_catalog.pdf",
});

console.log(doc.documentId, doc.status); // "processing"

2. APIプッシュ（構造化データ）

構造化データをプログラムでプッシュします。スクレイパー、在庫フィード、価格トラッカー、その他の外部データソースに最適です。

await client.knowledge.insertFacts(projectId, {
  source: "inventory_sync",
  facts: [
    {
      entityType: "product",
      label: "Widget Pro X",
      properties: {
        price:    29.99,
        category: "electronics",
        inStock:  true,
        tags:     ["wireless", "bluetooth"],
      },
    },
  ],
  relationships: [
    { fromLabel: "Widget Pro X", toLabel: "Electronics", edgeType: "belongs_to" },
  ],
});

Upsertセマンティクス

同じラベル+タイプのエンティティが既に存在する場合、プロパティはマージされバージョンがインクリメントされます。すべての変更はソースとタイムスタンプ付きでバージョン履歴に記録されます。

SDK：挿入と検索

SDKを使用してサーバーからデータをプッシュし検索します：

import { Sonzai } from "@sonzai-labs/agents";

const client = new Sonzai({ apiKey: "sk-..." });

// Insert entities
await client.knowledge.insertFacts(projectId, {
  source: "price_sync",
  facts: [
    {
      entityType: "item",
      label: "Charizard Base Set",
      properties: { price: 450, trend: "+12%", condition: "PSA 10" },
    },
  ],
  relationships: [
    { fromLabel: "Charizard Base Set", toLabel: "Fire Pokemon", edgeType: "is_type" },
  ],
});

// Search
const results = await client.knowledge.search(projectId, {
  query: "fire pokemon under 500",
  type: "item",
  limit: 10,
});
for (const r of results.results) {
  console.log(r.label, r.properties);
}

SDK：一括更新

bulkUpdateで外部データ（価格、在庫、統計）を一括同期します。変更されたフィールドのみが更新されるため、頻繁な同期に効率的です。

await client.knowledge.bulkUpdate(projectId, {
  source: "price_sync",
  updates: [
    { label: "Charizard Base Set", entityType: "item", properties: { price: 460 } },
    { label: "Blastoise Base Set", entityType: "item", properties: { price: 390 } },
  ],
});

エンティティスキーマ

型付きフィールドでカスタムエンティティタイプを定義します。スキーマは抽出をガイドし、プラットフォームがどのフィールドを探すべきかを正確に把握します。サポートされるタイプ：string、number、boolean、date、enum、array。

await client.knowledge.createSchema(projectId, {
  entityType: "pokemon_card",
  description: "Collectible trading cards",
  fields: [
    { name: "price",     type: "number", required: true },
    { name: "condition", type: "enum",   enumValues: ["PSA 10", "PSA 9", "Raw"] },
    { name: "set",       type: "string", required: true },
    { name: "rarity",    type: "enum",   enumValues: ["Common", "Uncommon", "Rare", "Ultra Rare"] },
    { name: "tags",      type: "array" },
  ],
  similarityConfig: {
    enabled: true,
    threshold: 0.7,
    fieldWeights: { price: 0.3, set: 0.4, rarity: 0.3 },
  },
});

ナレッジグラフ

エンティティは型付き関係で接続されます。グラフは任意のエンティティタイプと関係タイプをサポートし、完全にドメイン非依存です。

ノードタイプ、ラベル、柔軟なプロパティを持つエンティティ。正規化されたラベル+タイプで重複排除。

エッジノード間の型付き関係（belongs_to、similar_to、located_inなど）。双方向トラバーサル。

類似性スキーマで有効にすると、プロパティの類似性スコアに基づいてエンティティ間にsimilar_toエッジが自動作成されます。

バージョン履歴すべての変更がソース、タイムスタンプ、以前の値とともにバージョン管理されます。コンプライアンスのための完全な監査証跡。

検索

すべてのエンティティラベルとプロパティにわたるフルテキスト検索。タイプフィルタリング、プロパティフィルター、関連エンティティを含むグラフトラバーサルをサポートします。

const results = await client.knowledge.search(projectId, {
  query:   "bluetooth speaker",
  type:    "product",
  limit:   10,
  filters: { in_stock: true },
});

for (const r of results.results) {
  console.log(r.label, r.score, r.properties);
  // r.related[] contains connected nodes from 1-hop traversal
}

レコメンデーションエンジン

フィールドマッチングに基づいてソースエンティティをターゲットエンティティにマッチングするルールを定義します。エンジンはフィードバックループを防止し、コンバージョンフィードバックを使用してレコメンデーションを改善します。

フィールドマッチング完全一致、範囲許容値、最小閾値、配列オーバーラップ、数値近接でマッチング。各ルールに設定可能な重みがあります。

コンバージョン追跡レコメンデーションがアクション（購入、登録）につながった時に記録。システムは時間とともに学習し改善します。

陳腐化フィルター設定可能なウィンドウ内に更新されていないエンティティはレコメンデーションから自動的に除外されます。

// Create a recommendation rule
const rule = await client.knowledge.createAnalyticsRule(projectId, {
  ruleType: "recommendation",
  name: "Similar cards",
  config: { matchFields: ["set", "rarity"], limit: 5 },
  enabled: true,
});

// Get recommendations
const recs = await client.knowledge.getRecommendations(
  projectId, rule.ruleId, sourceNodeId, 5
);
for (const rec of recs.results) {
  console.log(rec.label, rec.score);
}

// Record feedback (improves future recommendations)
await client.knowledge.recordFeedback(projectId, {
  ruleId:       rule.ruleId,
  sourceNodeId: sourceNodeId,
  targetNodeId: rec.nodeId,
  action:       "converted",  // "shown" | "converted"
});

トレンド分析

時間ウィンドウ（7日、30日、90日）でエンティティプロパティの変化を追跡します。上昇率上位、下落率上位、最もボラタイル、最高平均のランキングを取得します。

// Get trend rankings
const trends = await client.knowledge.getTrendRankings(projectId, {
  ruleId: ruleId,
  type:   "top_gainers",   // "top_gainers" | "top_losers" | "most_volatile" | "highest_avg"
  window: "30d",           // "7d" | "30d" | "90d"
  limit:  10,
});

for (const item of trends.rankings) {
  console.log(item.label, item.currentValue, item.changePercent);
}

エージェントによるナレッジの活用

会話中、AIエージェントはナレッジベースをクエリする knowledge_searchツールにアクセスできます。事実をハルシネーションする代わりに、エージェントはグラフから正確なデータを取得します。エンティティプロパティ、関係、レコメンデーションを含みます。

User: "What's the best card under $500?"
       |
       v
Agent calls knowledge_search("cards under 500")
       |
       v
KB returns: Charizard ($450, +12%), Blastoise ($380, +8%)
       |
       v
Agent: "Charizard Base Set at $450 is trending up 12%
        this month -- great investment pick under $500."

根拠のある応答

ナレッジに裏付けされた応答は実際のデータに基づいています。エージェントはリアルタイムでグラフをクエリするため、現在の価格、在庫レベル、スペック、関係を把握しています。

ユースケース

価格トラッカー毎時価格をスクレイピングしAPIでプッシュ。エージェントが実データで「何が上昇中？」に回答。トレンドルールが上昇/下落を追跡。

不動産MLSフィードから物件リストをプッシュ。レコメンデーションルールが予算、部屋数、地域でバイヤーと物件をマッチング。

Eコマース製品カタログをアップロード。類似性検出が関連製品をリンク。エージェントが好みとコンバージョンデータに基づいてレコメンド。

社内ナレッジ従業員ハンドブック、ポリシー文書、製品マニュアルをアップロード。エージェントが正確でソース付きの情報で質問に回答。

製品カタログAPI経由で製品データをプッシュ。エージェントが現在のデータを使用してオプション、設定、レコメンデーションについてユーザーにアドバイス。

APIリファレンス

すべてのエンドポイントは Authorization: Bearer {api_key}ヘッダーを使用します。

エンドポイント	メソッド	目的
/knowledge/documents	POST	ドキュメントアップロード（マルチパート）
/knowledge/documents	GET	ステータス付きドキュメント一覧
/knowledge/documents/{docId}	DELETE	ドキュメント削除
/knowledge/facts	POST	エンティティと関係の作成/更新
/knowledge/search?q=...	GET	フィルター付きフルテキスト検索
/knowledge/nodes	GET	ノード一覧（タイプフィルター可）
/knowledge/nodes/{nodeId}	GET	エッジと履歴付きノード取得
/knowledge/schemas	POST	エンティティスキーマ作成
/knowledge/schemas	GET	スキーマ一覧
/knowledge/schemas/{schemaId}	PUT	スキーマ更新
/knowledge/stats	GET	KB統計取得
/knowledge/analytics/rules	POST	分析ルール作成
/knowledge/analytics/rules	GET	ルール一覧
/knowledge/analytics/rules/{ruleId}/run	POST	ルール実行トリガー
/knowledge/recommendations	GET	事前計算済みレコメンデーション取得
/knowledge/trends	GET	トレンド集計取得
/knowledge/trends/rankings	GET	トレンドランキング取得
/knowledge/conversions	GET	コンバージョン統計取得
/knowledge/feedback	POST	レコメンデーションフィードバック記録

ベースパス

上記のすべてのパスは /api/v1/projects/{projectId}からの相対パスです。プロジェクトIDはダッシュボードのプロジェクトページから取得してください。

← エージェント生成評価とシミュレーション→