构建一个能记住用户、使用工具并查询知识库的任务型智能体。任务型智能体不需要人格或情绪系统就能完成工作 — 本指南告诉你该接什么、可以跳过什么。

本快速入门适用于构建 AI 员工或个人 AI — 帮助用户完成工作的任务型智能体。典型场景：支持工程师、销售开发代表、收件箱助手、入职引导。

**你将构建的内容：**一个客户支持智能体，它能 (1) 跨会话记住每位用户，(2) 通过自定义工具创建工单和查询订单状态，(3) 从知识库中回答产品问题。

可以跳过的内容：情绪系统。情绪在后台仍然运行，但除非你主动启用，否则不会影响回复。人格保持最简 — 一个专业语调配置就足够了。

1. 创建项目并获取 API 密钥

前往 platform.sonz.ai，创建项目并生成 API 密钥。所有请求使用 Bearer 认证：

Authorization: Bearer sk_your_api_key

2. 创建智能体

给智能体设置一个最简的专业人格 — 高尽责性、中等宜人性、低神经质。这就是任务型智能体所需的全部配置。

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

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

const agent = await client.agents.create({
name: "Atlas",
bio: "Atlas is a calm, precise support engineer who answers product questions and handles tickets.",
big5: {
  openness: 0.55,
  conscientiousness: 0.85,
  extraversion: 0.5,
  agreeableness: 0.7,
  neuroticism: 0.2,
},
});

console.log(agent.agent_id);

3. 创建每用户实例

对于服务多个终端用户的任务型智能体，使用实例为每位用户在同一智能体定义下提供独立的记忆作用域。

const instance = await client.agents.instances.create("agent-id", {
name: "user-42",
description: "Support context for user 42",
});

所有以 instance_id = "user-42" 为作用域的记忆、自定义状态和通知，与其他用户的上下文完全隔离。

4. 播种智能体对该用户的了解

预加载用户信息，让智能体的第一次回复就能体现上下文 — 无冷启动问题。

await client.agents.memory.seed("agent-id", {
userId: "user-42",
memories: [
  { text: "User's name is Priya Kapoor.", factType: "fact" },
  { text: "Priya is on the Enterprise plan, renewed 2026-03-15.", factType: "fact" },
  { text: "Priya reported a billing issue last week (ticket #4821, resolved).", factType: "event" },
],
});

5. 注册自定义工具

工具让 LLM 在推理过程中调用你的后端。Sonzai 不执行工具 — 它返回工具调用，由你的后端执行，然后你在下一轮将结果传回。

await client.agents.sessions.setTools("agent-id", {
userId: "user-42",
tools: [
  {
    name: "create_ticket",
    description: "Create a support ticket for the user.",
    parameters: {
      type: "object",
      properties: {
        subject: { type: "string" },
        priority: { type: "string", enum: ["low", "normal", "high"] },
      },
      required: ["subject"],
    },
  },
  {
    name: "lookup_order",
    description: "Fetch the latest order status by order ID.",
    parameters: {
      type: "object",
      properties: { orderId: { type: "string" } },
      required: ["orderId"],
    },
  },
],
});

6. 上传知识库

将产品文档、内部 FAQ 或操作手册指向智能体。知识库以项目为作用域 — 项目中的所有智能体均可搜索。

import { readFileSync } from "node:fs";

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

启用 knowledge_search 能力后，智能体在对话过程中会自动搜索知识库。

7. 对话

流式获取回复。智能体会自动使用记忆、知识库和工具。

for await (const event of client.agents.chatStream({
agent: "agent-id",
userId: "user-42",
instanceId: instance.instance_id,
messages: [{ role: "user", content: "Hi, did my latest invoice go through?" }],
})) {
const delta = event.choices?.[0]?.delta?.content;
if (delta) process.stdout.write(delta);
}

回复结束后，记忆提取会自动运行 — 智能体会记住发生的事情，无需你做任何操作。

8. 轮询主动通知（可选）

智能体可以安排后续跟进 — 例如"明天回来查看工单 #4821"。定期轮询通知队列，或注册 webhook。

const pending = await client.agents.notifications.list("agent-id", { userId: "user-42", status: "pending" });

下一步

任务完成、通知和 SLA 的实时事件回调。

完整集成指南

深入了解每个 SDK 接口和集成路径。

当前 SDK 版本：TypeScript 1.1.3 · Python 1.1.4 · Go 1.2.0（截至 2026-04-17）

AI 员工与个人 AI — 快速入门