Sonzai Docs

Quickstart

Get your first AI agent running with the Mind Layer.

1. Create a Project

Go to Projects and create a new project. A project groups your agents and provides an API key for authentication.

2. Get Your API Key

In your project settings, generate an API key. This key authenticates all REST API calls to the Mind Layer.

# All requests require Bearer auth
Authorization: Bearer YOUR_API_KEY

3. Create an Agent

Create an agent via the SDK. The platform derives a full personality profile, speech patterns, and emotional tendencies from your Big5 scores.

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

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

// Derive a stable UUID from your own entity ID
const MY_NAMESPACE = "your-uuid-namespace-here";
const agentId = uuidv5("support-agent-001", MY_NAMESPACE);

const agent = await client.agents.create({
  agentId,           // pass your own UUID — safe to repeat
  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); // same UUID every time

Idempotent by Design

Agent creation is always a create-or-update. Calling it twice with the same ID updates the existing agent — it never errors or creates a duplicate. This means your startup code, CI pipelines, and provisioning scripts can call agents.create() unconditionally.

With agentIdServer uses your UUID directly. Recommended — link agents to your own entity IDs (agents, assistants, employees) for a deterministic mapping you control.
Without agentIdServer derives a UUID from your project ID + agent name. The same name always maps to the same agent within your project.

4. Chat with Your Agent

Use streaming chat to get real-time AI responses. The platform automatically handles context, memory, and state updates.

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

Server-Side Only

The SDK is for server-side use only. Never expose API keys in client-side code. For web apps, proxy through your backend. See the Integration Guide for examples.

5. Track Over Time

The dashboard shows personality shifts, memory growth, mood patterns, and relationship dynamics. All systems update automatically as users interact.

Next Steps

← OverviewArchitecture→