Sonzai Docs

快速开始

使用心智层快速运行您的第一个 AI 智能体。

1. 创建项目

前往 项目页面 并创建一个新项目。项目用于分组管理您的智能体，并提供用于身份验证的 API 密钥。

2. 获取 API 密钥

在项目设置中生成 API 密钥。此密钥用于验证所有发送到心智层的 REST API 请求。

# 所有请求都需要 Bearer 认证
Authorization: Bearer YOUR_API_KEY

3. 创建智能体

创建智能体有两种方式：使用大五人格分数显式定义人格特质，或通过自然语言提示自动生成。

方式 A：通过提示生成

用自然语言描述您的智能体，平台将自动生成人格、简介和种子记忆。

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

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

const agent = await client.generation.generateAndCreate({
  name: "Luna",
  description: "A cheerful and curious AI assistant who loves helping developers debug code. She's patient, witty, and always encouraging.",
  language: "en",
});

console.log(agent.agentId);        // 自动生成的 UUID
console.log(agent.personality);    // 从描述推导的完整大五人格档案

方式 B：使用大五人格分数定义

如需精确控制，可使用显式的大五人格分数创建智能体。平台会根据您的分数推导出完整的人格档案、语言风格和情绪倾向。

import { Sonzai } from "@sonzai-labs/agents";
import { v5 as uuidv5 } from "uuid";

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

// 从您自己的实体 ID 推导一个稳定的 UUID
const MY_NAMESPACE = "your-uuid-namespace-here";
const agentId = uuidv5("support-agent-001", MY_NAMESPACE);

const agent = await client.agents.create({
  agentId,           // 传入您自己的 UUID — 可安全重复调用
  name: "Luna",
  gender: "female",
  big5: {
    openness:          0.75,
    conscientiousness: 0.60,
    extraversion:      0.80,
    agreeableness:     0.70,
    neuroticism:       0.30,
  },
  language: "en",
});

console.log(agent.agentId); // 每次都是相同的 UUID

幂等设计

智能体创建始终是 创建或更新操作。使用相同 ID 重复调用会更新现有智能体 — 不会报错也不会创建重复项。这意味着您的启动代码、CI 流水线和配置脚本可以无条件调用 agents.create()。

带 agentId服务器直接使用您的 UUID。推荐方式 — 将智能体与您自己的实体 ID（代理、助手、员工）关联，实现您可控的确定性映射。
不带 agentId服务器根据您的项目 ID + 智能体名称推导 UUID。同一名称在项目内始终映射到同一智能体。

4. 与智能体对话

使用流式聊天获取实时 AI 响应。平台自动处理上下文、记忆和状态更新。

for await (const event of client.agents.chatStream("agent-id", {
  messages: [{ role: "user", content: "I had a great day hiking!" }],
  userId: "user-123",
})) {
  process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

仅限服务端使用

SDK 仅供服务端使用。切勿在客户端代码中暴露 API 密钥。对于 Web 应用，请通过后端代理。参见 集成指南 获取示例。

5. 持续追踪

仪表板展示人格变化、记忆增长、情绪模式和关系动态。所有系统在用户交互时自动更新。

下一步

← 概述架构→