构建一个面向 CRM、支持、内部工具或合规场景的工作流感知 AI 智能体。多实例隔离、webhook 驱动事件、项目级知识库、评估运行和审计就绪记忆 — 一站式完成。

本快速入门适用于构建企业级 AI 智能体 — 嵌入业务工作流的智能体。典型场景：CRM 副驾驶、一线支持、内部知识助手、销售资质审核机器人、合规审查员。

**你将构建的内容：**一个销售资质审核智能体，按工作空间运行，通过 webhook 接收 CRM 的交易事件，从产品文档中检索信息，以自定义状态追踪工作流阶段，并在每次发版前运行评估标准。

**你将用到的能力：**多实例隔离、项目级知识库、自定义状态、webhook、工具和评估运行。

1. 创建项目、API 密钥和 webhook 密钥

在 platform.sonz.ai 中创建项目，生成 API 密钥和 webhook 签名密钥。企业部署通常按环境（开发、预发布、生产）划分 API 密钥作用域。

export SONZAI_API_KEY=sk_...
export SONZAI_WEBHOOK_SECRET=whsec_...

2. 创建智能体

使用中性专业人格。保持 neuroticism 低值，避免情绪漂移影响回复。

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

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

const agent = await client.agents.create({
name: "Pilot-SDR",
bio: "Pilot-SDR qualifies inbound leads, answers product questions, and hands off to humans when appropriate. Professional, concise, and never embellishes.",
big5: {
  openness: 0.5,
  conscientiousness: 0.9,
  extraversion: 0.55,
  agreeableness: 0.65,
  neuroticism: 0.15,
},
});

3. 创建每工作空间实例

每个客户工作空间获得独立实例。以 instance_id = workspace-id 为作用域的记忆、自定义状态和通知保持隔离 — 这对多租户 SaaS 和合规至关重要。

const workspace = await client.agents.instances.create("agent-id", {
name: "acme-corp",
description: "Workspace for Acme Corp account",
});

作用域模式和生命周期管理参见多实例。

4. 将产品文档上传到知识库

知识库以项目为作用域 — 项目中的所有智能体搜索同一语料库。可上传 PDF、推送结构化实体，或两者兼用。

import { readFileSync } from "node:fs";

const pdf = readFileSync("./product-one-pager.pdf");
await client.knowledge.uploadDocument("project-id", "product-one-pager.pdf", pdf, "application/pdf");

// Or push structured facts
await client.knowledge.insertFacts("project-id", {
entities: [
  { label: "Plan: Growth", properties: { price: 299, seats: 10 } },
  { label: "Plan: Enterprise", properties: { price: "custom", seats: "unlimited" } },
],
});

5. 用自定义状态追踪工作流阶段

每笔交易或案例都处于某个阶段。将其存储为自定义状态，让智能体在每次对话时都能看到它，并据此推断下一步行动。

await client.agents.customStates.create("agent-id", {
key: "deal_stage",
value: "discovery",
scope: "per-user-instance",
userId: "[email protected]",
instanceId: workspace.instance_id,
});

6. 注册人工交接和 CRM 同步工具

企业级智能体始终需要一个转给人工的出口，以及写回系统记录的能力。

await client.agents.sessions.setTools("agent-id", {
userId: "[email protected]",
instanceId: workspace.instance_id,
tools: [
  {
    name: "handoff_to_human",
    description: "Escalate this conversation to a human rep and stop the agent.",
    parameters: { type: "object", properties: { reason: { type: "string" } }, required: ["reason"] },
  },
  {
    name: "update_deal_stage",
    description: "Advance the deal to a new stage in the CRM.",
    parameters: {
      type: "object",
      properties: {
        stage: { type: "string", enum: ["discovery", "qualified", "demo", "proposal", "closed_won", "closed_lost"] },
      },
      required: ["stage"],
    },
  },
],
});

7. 注册 webhook 以接收 CRM 事件

当 CRM 中的交易阶段发生变化时，将事件推送到 Sonzai。智能体在下一次对话时将其视为"工作流事件"并自然地做出响应。

await client.webhooks.register("on_wakeup_ready", {
webhookUrl: "https://api.yourcorp.com/sonzai/wakeups",
});

await client.webhooks.register("on_recurring_event_due", {
webhookUrl: "https://api.yourcorp.com/sonzai/schedules",
});

每个 webhook 请求均使用 HMAC-SHA256 签名 — 在执行操作前用你的密钥验证。完整事件目录、重试策略和验证示例参见 Webhook 与通知。

8. 对话

for await (const event of client.agents.chatStream({
agent: "agent-id",
userId: "[email protected]",
instanceId: workspace.instance_id,
messages: [{ role: "user", content: "Which plan fits a team of 12?" }],
})) {
const delta = event.choices?.[0]?.delta?.content;
if (delta) process.stdout.write(delta);
}

9. 通过评估运行把控发版质量

在发布提示词变更或新智能体版本前，用评估标准运行测试。对人格漂移、事实准确性和工具调用正确性进行评分。

// 启动模拟 + 评分运行，立即返回。
const ref = await client.agents.runEvalAsync("agent-id", {
templateId: "template_lead_qualification_v3",
simulationConfig: { turnsPerScenario: 6 },
});

// 评估完成后读取运行记录（或通过 streamEvents 实时流式获取）。
const result = await client.evalRuns.get(ref.runId);
console.log(result.scoreOverall, result.scoresByCategory);

构建评分标准和模拟用户参见评估。