追踪每个用户拥有的工具、许可证和订阅，并通过知识库中的实时成本数据进行丰富。完成本教程后，您将拥有一个能告诉用户其总订阅支出、成本变化以及应考虑的替代方案的智能体——所有这些都基于真实数据。

您将构建什么

一个包含 market_price 和层级信息的 software_license 实体知识库架构
一个通过 bulkUpdate 将实时定价数据推送到知识库的成本同步管道
一个具有 inventory 能力的智能体，在对话中自动追踪已分配的工具
一个将用户分配与当前知识库定价数据关联的组合查询

1. 定义实体架构

架构告诉知识库应为每种实体类型提取和索引哪些字段。为 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 插入第一批实体。这也是在上线前加载历史数据的方式。包含关系信息，以便知识库能推荐替代或互补工具。

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）运行成本同步任务，从供应商数据源获取当前定价并推送到知识库。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
});

您也可以在仪表板中设置：前往 智能体 > 您的智能体 > 能力 并启用库存。

5. 让智能体在对话中追踪资源

启用库存后，当用户提到他们使用的工具或订阅时，智能体会自动调用 sonzai_inventory_update。您只需正常聊天——平台会处理知识库解析和存储。

// 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 ?? "");
}

知识库解析原理

平台在知识库中搜索物品描述。如果恰好匹配一个节点，则自动关联。如果有多个候选，响应会返回 status: "disambiguation_needed" 和候选列表，以便智能体向用户确认。

6. 查询丰富后的组合

使用 mode="value" 获取每个用户资源与最新知识库定价数据的关联。平台自动计算 gain_loss：(market_price - purchase_price) x 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,000 项。对于更大的导入，请拆分为多次调用或使用仪表板中的 CSV 导入功能。

下一步

在知识库中设置推荐规则，向用户推荐替代工具
添加趋势追踪（7天/30天/90天）以支持"最大成本增长"报告
在 仪表板 > 智能体 > 您的智能体 > 用户 > 选择用户 > 库存/资产 中查看每用户库存
阅读知识库参考了解架构、分析规则和全文搜索

资源库存 + 知识库