各ユーザーが持つツール、ライセンス、サブスクリプションを追跡し、ナレッジベースからのリアルタイムコストデータで充実させます。このチュートリアルを終える頃には、ユーザーのサブスクリプション総額、コスト変動、検討すべき代替ソリューションをすべて実際のデータに基づいて回答できるエージェントが完成します。

構築するもの

market_price とティア情報を持つ software_license エンティティのナレッジベーススキーマ
bulkUpdate を介してライブ価格データをKBにプッシュするコスト同期パイプライン
会話中に割り当てられたツールを自動追跡する inventory 機能付きエージェント
ユーザーの割り当てと現在のKB価格データを結合するポートフォリオクエリ

1. エンティティスキーマの定義

スキーマは、各エンティティタイプについてKBがどのフィールドを抽出・インデックス化するかを指定します。software_license 用のスキーマを作成して、プラットフォームにライセンスデータの保存・検索方法を伝えます。

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

const client = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const PROJECT_ID = "proj_abc123";

await client.knowledge.createSchema(PROJECT_ID, {
entity_type: "software_license",
display_name: "Software License",
fields: [
  { name: "market_price",  type: "number",  indexed: true  },
  { name: "tier",          type: "string",  indexed: true  },
  { name: "category",      type: "string",  indexed: true  },
  { name: "license_type",  type: "string",  indexed: false },
  { name: "trend_30d",     type: "string",  indexed: false },
],
});

スキーマの作成は一度だけで十分です。それ以降、プラットフォームはそのタイプのすべてのエンティティを検証・インデックス化します。

2. 初期データのシーディング

insertFacts を使用して最初のエンティティセットを挿入します。これは本番稼働前の履歴データのロードにも使用できます。KBが代替または補完ツールの推奨を表示できるよう、リレーションシップも含めます。

await client.knowledge.insertFacts(PROJECT_ID, {
entities: [
  {
    type: "software_license",
    label: "Figma Enterprise",
    properties: {
      market_price: 75,
      tier: "Enterprise",
      category: "Design Tools",
      license_type: "per-seat-annual",
      trend_30d: "+5%",
    },
  },
  {
    type: "software_license",
    label: "Slack Business+",
    properties: {
      market_price: 12.50,
      tier: "Business",
      category: "Communication",
      license_type: "per-seat-monthly",
      trend_30d: "+3%",
    },
  },
  {
    type: "category",
    label: "Design Tools",
    properties: { vendor_count: 18, avg_seat_cost: 45 },
  },
],
relationships: [
  { from_label: "Figma Enterprise",  to_label: "Design Tools", edge_type: "belongs_to" },
  { from_label: "Slack Business+",   to_label: "Communication", edge_type: "belongs_to" },
  { from_label: "Figma Enterprise",  to_label: "Slack Business+", edge_type: "commonly_bundled" },
],
source: "seed_v1",
});

3. bulkUpdateで価格を最新に保つ

スケジュール（例：日次cron）でコスト同期ジョブを実行し、ベンダーデータソースから最新の価格を取得してKBにプッシュします。bulkUpdate はラベルで一致する既存ノードにプロパティをマージします -- 削除して再挿入する必要はありません。

// cost-sync.ts — run daily
import { Sonzai } from "@sonzai-labs/agents";
import { fetchLatestPricing } from "./vendor-api"; // your data source

const client = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const PROJECT_ID = "proj_abc123";

async function syncPricing() {
const pricing = await fetchLatestPricing(); // [{ name, price, trend }]

await client.knowledge.bulkUpdate(PROJECT_ID, {
  updates: pricing.map((license) => ({
    entity_type: "software_license",
    label: license.name,
    properties: {
      market_price: license.price,
      trend_30d: license.trend,
      last_synced: new Date().toISOString(),
    },
    // upsert: true — creates the node if it doesn't exist yet
    upsert: true,
  })),
});

console.log(`Synced ${pricing.length} license prices`);
}

syncPricing();

バッチサイズ

100アイテム以下のバッチは同期的に処理されます（即時レスポンス）。より大きなバッチはキューに入れられ非同期で処理されます -- レスポンスには完了をポーリングできるジョブIDが含まれます。

4. エージェントでインベントリを有効化

エージェントで inventory と knowledge 機能を有効にします。これにより、エージェントに sonzai_inventory_update と sonzai_inventory ツールが自動的に付与されます -- プロンプトエンジニアリングは不要です。

const AGENT_ID = "agent_xyz";

await client.agents.updateCapabilities(AGENT_ID, {
inventory: true,   // enables sonzai_inventory_update + sonzai_inventory tools
knowledge: true,   // enables knowledge_search tool
project_id: PROJECT_ID,  // which KB to join against
});

ダッシュボードからも設定できます：Agents → あなたのエージェント → Capabilities で Inventory をオンにしてください。

5. 会話中にエージェントにリソースを追跡させる

インベントリが有効になると、ユーザーがツールやサブスクリプションについて言及するたびに、エージェントは自動的に sonzai_inventory_update を呼び出します。通常通りチャットするだけで、プラットフォームがKBの解決とストレージを処理します。

// Your backend chat endpoint
for await (const event of client.agents.chatStream(AGENT_ID, {
userId: "user_123",
messages: [
  {
    role: "user",
    content: "We just provisioned 10 Figma Enterprise seats at $75/seat.",
  },
],
})) {
// The agent streams its reply — and internally calls
// sonzai_inventory_update({ action: "add", item_type: "software_license",
//   description: "Figma Enterprise", properties: { plan: "Enterprise",
//   purchase_price: 75, quantity: 10 } })
// The platform resolves the KB node, stores the link, and the agent
// continues the conversation without interruption.
process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

KB解決の仕組み

プラットフォームはKB内でアイテムの説明を検索します。完全に一致するノードが1つある場合、自動的にリンクされます。複数の候補がある場合、レスポンスは候補リスト付きの status: "disambiguation_needed" を返し、エージェントがユーザーに確認を求めることができます。

6. エンリッチされたポートフォリオのクエリ

mode="value" を使用して、各ユーザーリソースを最新のKB価格データと結合して取得します。プラットフォームは gain_loss を自動計算します：(market_price - purchase_price) × quantity。

const portfolio = await client.agents.inventory.query(AGENT_ID, "user_123", {
mode: "value",
project_id: PROJECT_ID,
});

// portfolio.items:
// [
//   {
//     fact_id: "fact_abc",
//     item_label: "Figma Enterprise",
//     kb_node_id: "node_xyz",
//     user_properties: { plan: "Enterprise", purchase_price: 75, quantity: 10 },
//     market_properties: { market_price: 80, tier: "Enterprise", trend_30d: "+5%" },
//     gain_loss: 50,
//   },
// ]
// portfolio.totals: { "market_price:sum": 800, "*:count": 10 }

console.log(`Portfolio value: $${portfolio.totals?.["market_price:sum"]}`);
console.log(`Total cost change: $${portfolio.items.reduce((s, i) => s + i.gain_loss, 0)}`);

mode="aggregate" と aggregations パラメーターを使用して、すべてのリソースを一覧表示せずにポートフォリオレベルの合計を取得することもできます -- 多くのサブスクリプションを持つ組織に便利です。

// Aggregate: total count + total subscription cost, grouped by item_type
const agg = await client.agents.inventory.query(AGENT_ID, "user_123", {
mode: "aggregate",
aggregations: "market_price:sum,*:count",
group_by: "item_type",
project_id: PROJECT_ID,
});
// agg.totals: { "market_price:sum": 875, "*:count": 12 }
// agg.groups: [{ group: "software_license", values: { sum: 875, count: 12 } }]

7. 既存サブスクリプションのバッチインポート

ユーザーが既にサブスクリプションのセットを持っている場合（CSV、調達システムのエクスポートなど）、エージェントが会話中に各リソースを発見するのを待つのではなく、一括でインポートします。

await client.agents.inventory.batchImport(AGENT_ID, "user_123", {
item_type: "software_license",
project_id: PROJECT_ID,
items: [
  {
    description: "Figma Enterprise",
    properties: { quantity: 10, plan: "Enterprise", purchase_price: 75 },
  },
  {
    description: "GitHub Enterprise",
    properties: { quantity: 25, plan: "Enterprise", purchase_price: 21 },
  },
],
});

バッチあたり最大1,000アイテム

バッチエンドポイントは1回の呼び出しで最大1,000アイテムを処理します。より大きなインポートの場合は、複数の呼び出しに分割するか、ダッシュボードのCSVプライミング機能を使用してください。

次のステップ

KBにレコメンデーションルールを設定して、ユーザーに代替ツールを表示
トレンドトラッキング（7日/30日/90日）を追加して「最大のコスト増加」レポートを実現
ユーザーごとのインベントリを Dashboard → Agents → あなたのエージェント → Users → ユーザーを選択 → Inventory / Assets でライブ確認
スキーマ、分析ルール、全文検索についてはナレッジベースリファレンスを参照

リソースインベントリ＋ナレッジベース