Introducing the Sonzai SDK v1: Production-Ready AI Agents in 10 Minutes

Today we're shipping v1 of the Sonzai SDK for TypeScript, Python, and Go. One API key, one consistent interface — everything you need to build AI agents that remember, learn, and grow.

Most AI integrations are stateless. You send a prompt, get a response, and the context disappears. The Sonzai Mind Layer changes that — persistent memory, evolving personality, real-time voice, a knowledge graph, and evaluation tooling, all accessible through a single SDK.

Install in Seconds

Pick your language and get going:

bun add @sonzai-labs/agents  # or: npm install @sonzai-labs/agents

pip install sonzai

go get github.com/sonz-ai/sonzai-go

All three SDKs are lightweight with zero heavy dependencies. TypeScript uses native Fetch (Node 18+), Python relies on httpx and pydantic, and Go uses only the standard library.

Create an Agent and Start Chatting

Go from zero to a working agent in under a minute:

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

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

// Create an agent with personality
const agent = await client.agents.create({
  name: "Atlas",
  bio: "A strategic advisor who remembers everything.",
  personalityDimensions: {
    openness: 85,
    conscientiousness: 90,
    extraversion: 60,
    agreeableness: 75,
    neuroticism: 20,
  },
});

// Chat with streaming
const stream = client.agents.chatStream({
  agent: agent.id,
  messages: [{ role: "user", content: "What should I focus on this quarter?" }],
  userId: "user_123",
});

for await (const event of stream) {
  if (event.type === "content") process.stdout.write(event.content);
}

import asyncio
from sonzai import AsyncSonzai

client = AsyncSonzai(api_key="your-api-key")

async def main():
    # Create an agent
    agent = await client.agents.create(
        name="Atlas",
        bio="A strategic advisor who remembers everything.",
        personality_dimensions={
            "openness": 85,
            "conscientiousness": 90,
            "extraversion": 60,
            "agreeableness": 75,
            "neuroticism": 20,
        },
    )

    # Chat with streaming
    async for event in client.agents.chat_stream(
        agent=agent.id,
        messages=[{"role": "user", "content": "What should I focus on this quarter?"}],
        user_id="user_123",
    ):
        if event.type == "content":
            print(event.content, end="")

asyncio.run(main())

package main

import (
    "context"
    "fmt"
    sonzai "github.com/sonz-ai/sonzai-go"
)

func main() {
    client := sonzai.NewClient("your-api-key")

    // Create an agent
    agent, _ := client.Agents.Create(context.Background(), &sonzai.CreateAgentOptions{
        Name: "Atlas",
        Bio:  "A strategic advisor who remembers everything.",
    })

    // Chat with streaming
    ch, _ := client.Agents.ChatStream(context.Background(), &sonzai.ChatOptions{
        Agent:    agent.ID,
        Messages: []sonzai.ChatMessage{{Role: "user", Content: "What should I focus on?"}},
        UserID:   "user_123",
    })

    for event := range ch {
        if event.Type == "content" {
            fmt.Print(event.Content)
        }
    }
}

That's it. Your agent is live, streaming responses, and building memory from every conversation.

Persistent Memory That Compounds

Every conversation is automatically stored, organized, and retrievable. Memories are structured as a hierarchical tree of atomic facts — each scored by importance and linked to specific sessions.

// Search an agent's memory
const results = await client.memory.search(agent.id, {
  query: "What does this user care about?",
  userId: "user_123",
});

results.results.forEach(r =>
  console.log(r.content, "— relevance:", r.score)
);

// View memory timeline by date range
const timeline = await client.memory.timeline(agent.id, {
  userId: "user_123",
  startDate: "2026-03-01",
  endDate: "2026-03-31",
});

// Seed memories at creation for instant context
await client.memory.seed(agent.id, {
  memories: [
    "Founded the company in 2023 after leaving finance.",
    "Has two kids and values work-life balance.",
    "Prefers direct, concise communication.",
  ],
  userId: "user_123",
});

Memory isn't just storage — it's the foundation for compounding intelligence. The more your users interact, the more valuable the agent becomes. A self-reinforcing loop that stateless AI can never replicate.

Personality That Evolves

Every agent ships with a Big Five personality model that naturally adapts through interaction. You set the starting point — the Mind Layer handles the rest.

# Get the full personality profile
profile = await client.personality.get(agent.id)

print(profile.profile.big5.openness)        # 85
print(profile.profile.big5.neuroticism)      # 20
print(profile.profile.dimensions.warmth)     # Derived from interactions

# See how the personality has shifted over time
shifts = await client.personality.get_recent_shifts(agent.id)
for shift in shifts.shifts:
    print(f"{shift.trait}: {shift.delta:+.1f}")

# Each user gets their own personality overlay
overlay = await client.personality.get_user_overlay(agent.id, "user_123")
print(overlay.overlay)  # How the agent specifically relates to this user

Personality overlays let the same agent feel different to different users — more formal with a CEO, more casual with a friend — while maintaining a coherent core identity.

Knowledge Base for Grounded Responses

Give your agents structured domain knowledge through a built-in knowledge graph. Product catalogs, real estate listings, company policies, pricing tables — anything your agent needs to give accurate, grounded answers.

// Populate the knowledge graph with property listings
await client.knowledge.insertFacts(projectId, {
  facts: [
    { subject: "123 Marina Bay", predicate: "type", object: "3BR Condo" },
    { subject: "123 Marina Bay", predicate: "asking_price", object: "$1,250,000" },
    { subject: "123 Marina Bay", predicate: "neighborhood", object: "Downtown Core" },
    { subject: "Downtown Core", predicate: "avg_psf", object: "$2,180" },
  ],
});

// Natural language search with graph traversal
const results = await client.knowledge.search(projectId, {
  query: "condos under 1.5M near downtown",
});

// Get recommendations based on user preferences
const recs = await client.knowledge.getRecommendations(projectId, {
  query: "family-friendly, close to MRT, budget 1.2M",
});

// Load company policies and internal docs
await client.knowledge.insertFacts(projectId, {
  facts: [
    { subject: "Expense Policy", predicate: "max_approval", object: "Manager approval up to $5,000" },
    { subject: "Expense Policy", predicate: "requires_receipt", object: "All expenses over $25" },
    { subject: "PTO Policy", predicate: "annual_days", object: "20 days for full-time employees" },
    { subject: "PTO Policy", predicate: "carryover", object: "Max 5 days to next year" },
  ],
});

// Employees can ask the agent about policies in natural language
const results = await client.knowledge.search(projectId, {
  query: "how many vacation days can I roll over?",
});

Under the hood, the knowledge base supports documents, versioned graph nodes, entity schemas, analytics rules, trend analysis, and recommendation scoring.

Real-Time Voice

Ship voice-enabled agents with full-duplex WebSocket streaming. The SDK handles token management, PCM audio encoding, and event routing so you don't have to.

// Get a short-lived voice token
const { token } = await client.voice.getToken(agent.id, {
  userId: "user_123",
  voiceName: "aria",
});

// Open a bidirectional voice stream
const voice = client.voice.stream(token);

voice.on("output_transcript", (text) => console.log("Agent:", text));
voice.on("audio", (pcm) => playAudio(pcm));
voice.on("input_transcript", (text) => console.log("User:", text));

// Send audio from microphone (16kHz, 16-bit, mono PCM)
microphone.on("data", (chunk) => voice.sendAudio(chunk));

// Or send text for text-to-speech
voice.sendText("Hello! How can I help you today?");

Voice sessions automatically capture emotions, extract facts into memory, and track relationship shifts — just like text conversations.

Evaluation and Simulation

Don't ship blind. The SDK includes evaluation and simulation tooling so you can test agent behavior before it ever reaches users.

# Run a multi-turn simulation with a user persona
run_ref = await client.agents.simulate_async(
    agent=agent.id,
    user_persona={
        "name": "Alex",
        "background": "New user, skeptical about AI assistants",
        "personality_traits": ["direct", "analytical"],
        "communication_style": "terse",
    },
    sessions=3,
    turns_per_session=10,
)

# Stream the simulation events in real time
async for event in client.eval_runs.stream_events(run_ref.run_id):
    print(event)

# Evaluate against a scoring rubric
result = await client.agents.evaluate(
    agent=agent.id,
    messages=test_conversation,
    template_id="your-eval-template",
)
print(f"Score: {result.score}/100")

Define custom scoring rubrics, run multi-turn simulations with synthetic personas, and track results across runs. This is how you go from prototype to production with confidence.

Everything Else You Need

The SDK covers the full Mind Layer API surface:

• Sessions — Manage conversation sessions with custom tool access per session
• Instances — Run isolated copies of the same agent for A/B testing or multi-tenant setups
• Custom States — Store arbitrary JSON scoped to agent, user, or instance level
• Inventory — Track items and assets per user with KB-joined valuations
• Mind Layer — Access mood, relationships, habits, goals, interests, and diary entries
• Webhooks — Real-time event notifications with delivery tracking
• Wakeups — Schedule proactive agent check-ins based on intent or occasion
• Generation — Generate bios, seed memories, images, and full profiles from a description
• User Priming — Pre-populate user context for instant personalization
• Custom Tools — Define JSON-schema tools that agents can invoke mid-conversation
• Consolidation — Compact and summarize memory trees for long-running agents
• Time Machine — Query historical agent state snapshots at any point in time

From Zero to Production in 10 Minutes

Here's the path:

1. Install the SDK — 10 seconds
2. Create an agent with personality and a bio — 30 seconds
3. Seed initial memories with domain context — 1 minute
4. Wire up chat with streaming in your app — 2 minutes
5. Insert knowledge base facts for grounded responses — 2 minutes
6. Add custom tools for agent-driven actions — 2 minutes
7. Run an evaluation to validate behavior before launch — 2 minutes

Everything works out of the box with sensible defaults. No infrastructure to deploy, no vector databases to manage, no embedding pipelines to build. The Mind Layer handles memory indexing, personality evolution, fact extraction, and retrieval — you just call the API.

Get Started

The SDKs are available now:

• TypeScript: bun add @sonzai-labs/agents (or npm install) — npm
• Python: pip install sonzai — PyPI
• Go: go get github.com/sonz-ai/sonzai-go — GitHub

Grab an API key at platform.sonz.ai, pick your language, and start building agents that remember.