快速开始
使用心智层快速运行您的第一个 AI 智能体。
1. 创建项目
前往项目页面，创建一个新项目。项目用于管理你的智能体，并提供用于身份验证的 API 密钥。
2. 获取 API 密钥
在项目设置中生成 API 密钥。该密钥用于验证所有发往心智层的 REST API 请求。
# 所有请求都需要 Bearer 认证
Authorization: Bearer YOUR_API_KEY3. 安装 SDK（也可以跳过）
选择适合你技术栈的接入方式。所有方式都连接到同一个托管 API —— 你可以混合使用（例如后端用 Python，再让 Claude Desktop 通过 MCP 连接做运维）。
pip install sonzai- Python 3.11+。同步（
Sonzai）和异步（AsyncSonzai）客户端同包发布。 - TypeScript 支持 Node.js >=18、Bun 和 Deno。零运行时依赖。
- Go 1.25+。仅依赖标准库。
- 使用 OpenClaw 路径前需先安装 OpenClaw 本身——详见 openclaw.ai（快速开始）。
- 完整指南：MCP · OpenClaw · REST API 参考。
API 密钥处理
TypeScript、Python 和 Go SDK 默认从环境变量 SONZAI_API_KEY 读取密钥 —— 只在你想自行管理时才显式传入（例如 new Sonzai({ apiKey: "sk-..." })）。OpenClaw 插件把密钥保存在 openclaw.json。MCP 服务器通过客户端配置传入的 SONZAI_API_KEY 环境变量获取密钥。
4. 创建智能体
创建智能体有两种方式：通过大五分数显式定义人格特征，或从自然语言提示词生成。
选项 A：从提示词生成
用自然语言描述你的智能体，平台自动生成人格、传记和种子记忆。
import { Sonzai } from "@sonzai-labs/agents";
const client = new Sonzai({ apiKey: "sk-..." });
const agent = await client.agents.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.agent_id); // 自动生成的 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.agent_id); // 每次相同的 UUID设计上的幂等性
智能体创建始终是创建或更新操作。使用相同 ID 调用两次会更新现有智能体——不会报错或创建副本。这意味着你的启动代码、CI 流水线和配置脚本可以无条件地调用 agents.create()。
- 带 agentId：服务器直接使用你的 UUID。推荐——将智能体链接到你自己的实体 ID（助手、员工等），建立你能控制的确定性映射。
- 不带 agentId：服务器从你的项目 ID + 智能体名称派生 UUID。相同名称在你的项目内始终映射到相同智能体。
5. 与你的智能体聊天
使用流式聊天获取实时 AI 响应。平台自动处理上下文、记忆和状态更新。
for await (const event of client.agents.chatStream({
agent: "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 应用，通过你的后端代理请求。参见集成指南获取示例。
6. 随时间追踪
仪表盘展示人格变化、记忆增长、情绪模式和关系动态。所有系统随用户交互自动更新。