Conversations

Real-time chat lifecycle: send messages, stream responses, and let the platform update agent state automatically.

Session Flow

Every conversation follows a simple three-step lifecycle:

1. Send a chat request   — Pass agent ID, user ID, application context, and messages
2. Receive stream        — Render tokens to the user in real time
3. Platform auto-updates — Memory, mood, relationships, and personality evolve

Chat (Non-Streaming)

For simple request-response flows, use the standard chat method.

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

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

const response = await client.agents.chat("agent-id", {
  messages: [{ role: "user", content: "Hello!" }],
  userId: "user-123",
  language: "en",
});

console.log(response.content);

Chat (Streaming)

Stream tokens as they arrive for a more responsive experience. Uses Server-Sent Events (SSE) under the hood.

for await (const event of client.agents.chatStream("agent-id", {
  messages: [{ role: "user", content: "Tell me a story" }],
  userId: "user-123",
  language: "en",
  timezone: "America/New_York",
})) {
  process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

SSE Format

The REST endpoint sends OpenAI-compatible SSE chunks. Each line starts with data: . The stream ends with data: [DONE].

Application Context

Pass application state per request so the agent can reference it during conversation. The platform doesn't cache this state — send it on every chat call.

for await (const event of client.agents.chatStream("agent-id", {
  messages: [{ role: "user", content: "What should I do next?" }],
  userId: "user-123",
  gameContext: {
    customFields: {
      department: "Engineering",
      currentTask: "Q2 roadmap review",
      ticketsOpen: 12,
      role: "Senior Developer",
    },
  },
})) {
  process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

Platform-Managed State Updates

After each interaction, the platform processes these automatically. No separate API calls needed.

Memory Extraction

Extracts facts, events, and commitments from the conversation.

Mood Update

Detected emotional themes shift mood dimensions.

Personality Evolution

Gradual Big5 shifts from interaction patterns.

Habit Tracking

Recurring patterns become tracked habits.

Relationship Update

Updates chemistry and relationship narrative.

Goal Progress

Records progress on active goals.

Tool Calling

Internal tools (memory, state) run automatically. You only configure opt-in tools for end-user capabilities:

Opt-In Tools

generate_imageGenerate an image from text prompt

generate_videoGenerate a video from text prompt

generate_soundGenerate a sound effect

generate_musicGenerate background music

generate_ttsText-to-speech conversion

Enable via SDK

for await (const event of client.agents.chatStream("agent-id", {
  messages: [{ role: "user", content: "Show me a sunset!" }],
  userId: "user-123",
  tools: ["generate_image"],
})) {
  if (event.type === "image") {
    console.log("Generated image:", event.imageUrl);
  }
}

Enable opt-in tools based on your product's capabilities. Memory and state tools are platform-managed.

← Emotions & Mood Knowledge Base→