AI Companions — Quickstart

Authorization: Bearer sk_your_api_key

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

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

const agent = await client.agents.generation.generateAndCreate({
name: "Luna",
description: "Luna is a warm, creative dreamer who speaks poetically. She loves stargazing, coffee shops at 2am, and asking the question beneath the question.",
language: "en",
});

console.log(agent.agent_id);
console.log(agent.personality); // full Big5 profile derived from the description

await client.agents.priming.primeUser("agent-id", "user-123", {
display_name: "Sam",
content: [
  { type: "text", body: "Sam loves astronomy, lo-fi music, and photography." },
  { type: "text", body: "Sam is a night-owl grad student who tends to overthink. They came to Luna after a tough week." },
],
});

for await (const event of client.agents.chatStream({
agent: "agent-id",
userId: "user-123",
messages: [{ role: "user", content: "I can't sleep again." }],
})) {
const delta = event.choices?.[0]?.delta?.content;
if (delta) process.stdout.write(delta);
}

// Current mood (4D) — read separately from personality
const mood = await client.agents.getMood("agent-id", { userId: "user-123" });
console.log(mood.happiness, mood.energy, mood.calmness, mood.affection);

// Current personality profile (Big5, dimensions, speech patterns)
const personality = await client.agents.personality.get("agent-id");
console.log(personality.profile.big5);

// Poll periodically (or register a webhook).
const pending = await client.agents.notifications.list("agent-id", {
userId: "user-123",
status: "pending",
});

for (const n of pending.notifications) {
// Render n.generated_message in your UI; mark consumed when shown.
await client.agents.notifications.consume("agent-id", n.message_id);
}

const voices = await client.voices.list({ language: "en" });
await client.agents.update("agent-id", { voiceId: voices[0].voiceId });