Generation

Generation covers two distinct capabilities: agent generation (spinning up a complete character — bio, personality, seed memories, avatar — from a text description) and media generation (producing images on demand during a chat turn). Both live under client.agents.generation and client.agents.image.

What you can build with it

• One-click character creation — spec a rough prompt, get a complete agent profile + avatar
• Avatar regeneration — refresh an agent's look as the character evolves over time
• Seed memories — plant backstory facts the agent "remembers" from day 1
• In-chat image generation — agent creates pictures as part of its responses
• Character templates — generate many similar agents from a shared base prompt

Quickstart

Generate a character + create the agent

The single fastest path: one call generates a full personality profile and provisions the agent. Safe to call on every deploy — if the agent already exists, the LLM is skipped.

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 assistant who loves helping developers debug code.",
language: "en",
});

console.log(agent.agent_id);

Generate an image in-chat

Call client.agents.image.generate with the agent ID and a prompt during or alongside a chat turn.

const image = await client.agents.image.generate("agent-id", {
prompt: "A serene mountain landscape at sunset",
});

console.log(image.url);          // public CDN URL
console.log(image.generationTimeMs);

Capabilities — image, music, and video generation

Three AgentCapabilities flags gate media generation. Each flag is a boolean on the agent, and each has a paired *UnlockedAt timestamp that records when the capability was granted (typically via a tier upgrade or admin enable). Generation calls fail if the flag is false.

imageGeneration is the only media flag you can toggle directly via update_capabilities(). musicGeneration and videoGeneration are platform-managed — they flip when your plan includes those capabilities. Use get_capabilities() to inspect their current state.

// Read current media capability flags
const caps = await client.agents.getCapabilities("agent-id");
console.log(caps.imageGeneration);  // true | false
console.log(caps.imageUnlockedAt);  // "2024-11-01T00:00:00Z"
console.log(caps.musicGeneration);  // true | false
console.log(caps.videoGeneration);  // true | false

// Enable image generation (if your plan allows it)
await client.agents.updateCapabilities("agent-id", { imageGeneration: true });

Core concepts

Character generation

Character generation takes a natural-language description and produces a structured agent profile. You can generate the profile and immediately create the agent (GenerateAndCreate), or generate the profile first for preview and commit only on user approval (GenerateCharacter).

Input: name, description, optional fields filter, optional gender, optional LLM provider/model override, optional regenerate flag.

Output: bio, personality prompt, Big5 scores, speech patterns, interests, dislikes, primary traits, dimensions, interaction preferences, behavioral traits, initial goals.

The Regenerate flag forces a fresh generation even when a cached profile is found — useful for iteration flows where the user wants a different result without deleting the agent.

// Preview without committing
profile, err := client.Agents.Generation.GenerateCharacter(ctx, sonzai.GenerateCharacterOptions{
    Name:        "Atlas",
    Description: "A stoic, wise mentor who speaks in metaphors and values patience above all.",
    Fields:      []string{"big5", "dimensions", "preferences", "behaviors"},
    Regenerate:  true,   // force a fresh pass
})

Bio generation (GenerateBio) and avatar regeneration (RegenerateAvatar) are narrower variants — they update a single attribute of an existing agent without touching the rest of the profile.

Seed memories work in two steps:

1. Generate — GenerateSeedMemories calls an LLM to produce backstory memories from the agent's personality, interests, and lore context.
2. Store — SeedMemories bulk-imports a list of memory objects (generated or hand-authored) into the agent's memory store.

You can run both steps separately for fine-grained control, or set storeMemories: true on the generate call to do both in one request.

Media generation

Image generation is agent-scoped: client.agents.image.generate(agentID, opts). The agent ID is used to apply the agent's visual style and context to the generation request.

Input: prompt (required), optional negative_prompt, optional model/provider override, optional output_bucket/output_path for custom storage routing.

Output: image_id, public_url, mime_type, generation_time_ms.

Images are generated synchronously — the call blocks until the image is ready and returns a public CDN URL. For high-throughput workflows, fan out parallel calls rather than queuing.

Full API

Combines with other features

With Personality — character generation sets initial Big5

generateCharacter (and generateAndCreate) returns a full Big5 profile derived from the description. The platform uses these scores directly as the agent's personality baseline — no manual personality.update call needed.

// Generate the profile — inspect Big5 before committing
const profile = await client.agents.generation.generateCharacter({
name: "Atlas",
description: "A stoic, wise mentor who speaks in metaphors and values patience above all.",
fields: ["big5", "dimensions", "preferences", "behaviors"],
});

console.log(profile.big5);
// { openness: 0.72, conscientiousness: 0.85, extraversion: 0.35,
//   agreeableness: 0.63, neuroticism: 0.22 }

// Then create with those exact scores
const agent = await client.agents.create({
name: "Atlas",
big5: profile.big5,
});

With Memory — seed memories plant backstory

Generate memories from the agent's personality context, then seed them into the memory store. They appear immediately in memory.list and are recalled in the agent's first conversations.

// Step 1: generate backstory memories from personality context
const generated = await client.agents.generation.generateSeedMemories("agent-id", {
agentName: "Luna",
trueInterests: ["astronomy", "poetry", "hiking"],
trueDislikes: ["loud noises", "dishonesty"],
generateOriginStory: true,
generatePersonalizedMemories: true,
});

console.log(`Generated ${generated.memories.length} memories`);

// Step 2: store them (or pass storeMemories: true above to do both in one call)
await client.agents.generation.seedMemories("agent-id", {
userId: "user-123",
memories: generated.memories,
});

// Step 3: verify they appear in memory
const stored = await client.agents.memory.list("agent-id", { userId: "user-123" });
console.log(stored);

With Conversations — image generation as a chat capability

Call image.generate within a chat turn to let the agent produce images as part of its response. Render the returned URL alongside the text content.

// Inside a chat turn handler
const response = await client.agents.chat({
agent: "agent-id",
userId: "user-123",
messages: [{ role: "user", content: "Draw me a cozy forest cabin at night." }],
language: "en",
});

// If the agent decides to produce an image, generate it
const image = await client.agents.image.generate("agent-id", {
prompt: "A cozy forest cabin at night, warm light through windows, snow falling",
});

// Render both in your UI
renderChatBubble(response.content);
renderImage(image.url);

In Practice

const agent = await client.agents.generation.generateAndCreate({
  name: userInput.name,
  description: userInput.description,
  language: "en",
});

Tutorials

• Tutorial: Seed memories from scratch

Next steps

• Personality — understand the Big5 profile that generation produces
• Memory — how seed memories integrate with the live memory system
• Conversations — wiring image generation into a chat turn