sonzai-go｜Sonzai Mind Layer 官方 Go SDK

access：来源确认 · go get github.com/sonz-ai/sonzai-go@v1.8.0

project_type：来源确认 · The official Go SDK for the [Sonzai Mind Layer API](https://sonz.ai). Build tenant runtimes that use Sonzai memory while calling their LLM provider directly.

# Sonzai Go SDK

[![Go Reference](https://pkg.go.dev/badge/github.com/sonz-ai/sonzai-go.svg)](https://pkg.go.dev/github.com/sonz-ai/sonzai-go)
[![Go Report Card](https://goreportcard.com/badge/github.com/sonz-ai/sonzai-go)](https://goreportcard.com/report/github.com/sonz-ai/sonzai-go)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

The official Go SDK for the [Sonzai Mind Layer API](https://sonz.ai). Build
tenant runtimes that use Sonzai memory while calling their LLM provider
directly.

Zero dependencies — Go standard library only.

## Requirements

- Go 1.25 or later

## Installation

```bash
go get github.com/sonz-ai/sonzai-go@v1.8.0
```

```go
import sonzai "github.com/sonz-ai/sonzai-go"
```

## Quick Start

```go
package main

import (
    "context"
    "fmt"

    sonzai "github.com/sonz-ai/sonzai-go"
)

func main() {
    // Reads SONZAI_API_KEY from env if the first arg is empty.
    client := sonzai.MustNewClient("")
    ctx := context.Background()

    // Sonzai Cloud supplies memory and tool definitions only.
    bundle, err := client.Runtime.ContextBundle(ctx, "your-agent-id",
        sonzai.RuntimeContextBundleParams{
            UserID: "user-123", SessionID: "session-123",
            CurrentMessage: "Hello!",
        })
    if err != nil { panic(err) }

    // Invoke OpenAI, Gemini, OpenRouter, or your own endpoint here, from this
    // runtime. Provider credentials and quota never pass through platform-api.
    fmt.Printf("context ready: %d system parts\n", len(bundle.SystemPromptParts))
}
```

`Client.Runtime` intentionally has no completion method. After a direct
provider call, use `ReportTurns` to persist the transcript and
`SignRuntimeUsageReport` + `SubmitUsageReport` for attributed billing. Standard
usage is benchmark provider cost × 1.33; BYOK/BYOM usage is a 33% Sonzai
service fee because the tenant pays its provider directly.

See the [examples/](examples/) directory for complete, runnable programs covering chat, agent lifecycle, memory, voice, and evaluation.

> **Using the OpenClaw plugin?** Your API key is stored in `openclaw.json` — no environment variables needed. See the [@sonzai-labs/openclaw-context](../sonzai-openclaw/) docs.

## Client & Configuration

```go
// Constructor with API key (falls back to SONZAI_API_KEY env var if empty)
client, err := sonzai.NewClient("")

// Or panic-on-error variant (for CLI tools and tests)
client := sonzai.MustNewClient("")

// Options
client := sonzai.MustNewClient("",
    sonzai.WithBaseURL("https://api.sonz.ai"),      // or SONZAI_BASE_URL env var
    sonzai.WithRuntimeBaseURL("https://runtime.example.com"), // or SONZAI_RUNTIME_BASE_URL env var
    sonzai.WithTimeout(60*time.Second),              // default 30s
    sonzai.WithHTTPClient(&http.Client{...}),        // custom transport / proxy / mTLS
)
```

Idempotent requests (GET, DELETE) automatically retry up to 3 times with exponential backoff on 429/502/503/504. POST/PUT/PATCH are not retried.

## Authentication

Get your API key from the [Sonzai Dashboard](https://platform.sonz.ai) under **Projects > API Keys**. Set it via argument or environment variable:

```bash
export SONZAI_API_KEY=sk-...
```

## Resources

The `Client` exposes these top-level resource groups:

| Resource | Purpose |
|---|---|
| `Agents` | Agent CRUD, chat, dialogue, context engine state |
| `Knowledge` | Project-scoped knowledge base (docs, graph, facts, search) |
| `Eval` | Evaluations, simulations, eval runs, templates (sub-package) |
| `Voices` | Global voice catalog |
| `Webhooks` | Webhook registration, rotation, delivery inspection |
| `ProjectConfig` / `AccountConfig` | Scoped key-value configuration |
| `CustomLLM` | Bring-your-own-model (BYOM) configuration |
| `ProjectNotifications` | Project notification polling |
| `Tenants` | Multi-tenant lookup |
| `APIKeys` | Project API key management |
| `Analytics` | Cost, usage, and real-time analytics |
| `UserPersonas` | User persona CRUD |
| `Storefront` | Agent marketplace publishing |
| `Org` | Organization billing and usage |
| `Workbench` | Internal simulation and debugging |
| `Support` | Support tickets |
| `Crm` | Runtime-local CRM adapter import and event feed |

Sub-resources on `client.Agents`:

```go
client.Agents.Memory        // memory tree, search, facts, timeline
client.Agents.Personality   // Big5, dimensions, deltas, overlays
client.Agents.Sessions      // session lifecycle
client.Agents.Instances     // parallel agent instances
client.Agents.Notifications // proactive notifications
client.Agents.CustomState   // scoped key-value state
client.Agents.Image         // image generation
client.Agents.Voice         // TTS, STT, live WebSocket streaming
client.Agents.Wakeups       // wakeup scheduling
client.Agents.Generation    // bio, character, seed memory generation
client.Agents.Priming       // user priming & batch import
client.Agents.Inventory     // user inventory
client.Agents.Schedules     // user-scoped recurring events
```

## Runtime CRM

The runtime CRM is served by a deployed `app-runtime` instance under
`/api/rt/crm/*`, not by the Sonzai platform API. Configure both the adapter
token and runtime base URL before using `client.Crm`:

```go
client := sonzai.MustNewClient("adapter-token",
    sonzai.WithRuntimeBaseURL("https://runtime.example.com"),
)

result, err := client.Crm.Import(ctx, []sonzai.CrmImportItem{{
    ExternalRef: "sf-123",
    FirstName:   "Grace",
    LastName:    "Hopper",
    Emails:      json.RawMessage(`["grace@example.com"]`),
}}, &sonzai.CrmImportOptions{TenantID: "tenant-a"})

events, err := client.Crm.Events(ctx, &sonzai.CrmEventsOptions{
    Cursor:   savedCursor,
    Limit:    100,
    TenantID: "tenant-a",
})
savedCursor = events.NextCursor
```

Only the adapter-token surface is exposed: bulk contact import and the cursor
event feed. Staff CRM CRUD routes are browser-session routes in the runtime and
are not part of the headless SDK surface.

## Bring Your Own Key (BYOK)

BYOK lets you register your own LLM provider API keys with a project. Once set,
upstream LLM calls for that project route through your key — token billing falls
on your provider account, not Sonzai's. Keys are encrypted at rest server-side
and are never returned by the API (only the key prefix and health metadata are
exposed). Requires `read:byok` / `write:byok` scopes on the API key you use to
call these endpoints.

```go
ctx := context.Background()

// List all configured BYOK providers for a project
keys, _ := client.BYOK.List(ctx, "project-id")
for _, k := range keys {
    fmt.Printf("%s: %s (active: %v)\n", k.Provider, k.HealthStatus, k.IsActive)
}

// Store or replace a key (validated against the provider before saving)
key, _ := client.BYOK.Set(ctx, "project-id", sonzai.BYOKProviderOpenAI, "sk-...")
fmt.Println("Stored prefix:", key.APIKeyPrefix)

// Enable or disable without rotating
client.BYOK.SetActive(ctx, "project-id", sonzai.BYOKProviderOpenAI, false)

// Re-run the provider health check on a stored key
result, _ := client.BYOK.Test(ctx, "project-id", sonzai.BYOKProviderGemini)
fmt.Println(result.HealthStatus) // "healthy" | "invalid" | "unknown"

// Remove a stored key (project falls back to platform billing)
client.BYOK.Delete(ctx, "project-id", sonzai.BYOKProviderXAI)
```

Provider constants: `sonzai.BYOKProviderOpenAI`, `sonzai.BYOKProviderGemini`,
`sonzai.BYOKProviderXAI`, `sonzai.BYOKProviderOpenRouter`.
REST path: `/api/v1/projects/{project_id}/byok-keys[/{provider}[/test]]`.

## Usage

### Agent CRUD

```go
agent, _ := client.Agents.Create(ctx, sonzai.CreateAgentOptions{
    Name:   "Aria",
    Gender: "female",
    Bio:    "A curious explorer who loves stargazing.",
    Big5: &sonzai.Big5Scores{
        Openness: 85, Conscientiousness: 60, Extraversion: 70,
        Agreeableness: 75, Neuroticism: 25,
    },
    // Tool capabilities are configurable at creation time:
    ToolCapabilities: &sonzai.AgentToolCapabilities{
        WebSearch:     true,
        RememberName:  true,
        KnowledgeBase: sonzai.Ptr(true), // enable project-scoped KB search
        MemoryMode:    "async",           // "sync" (default) or "async"
    },
})

fetched, _ := client.Agents.Get(ctx, agent.AgentID)
agents, _ := client.Agents.List(ctx, sonzai.ListAgentsOptions{PageSize: 20})
client.Agents.Delete(ctx, agent.AgentID)
```

### Chat (aggregated response)

```go
resp, _ := client.Agents.Chat(ctx, sonzai.AgentChatParams{
    AgentID: "agent-id",
    ChatOptions: sonzai.ChatOptions{
        Messages: []sonzai.ChatMessage{
            {Role: "user", Content: "Tell me about yourself"},
        },
        UserID:    "user-123",
        SessionID: "session-456", // auto-created if omitted
        Provider:  "gemini",
        Model:     "gemini-3.1-flash-lite",
    },
})
fmt.Println(resp.Content)
fmt.Println(resp.Usage.TotalTokens)
```

### Chat (streaming)

Two streaming patterns — callback and channel.

```go
// Callback
err := client.Agents.ChatStream(ctx, params, func(event sonzai.ChatStreamEvent) error {
    fmt.Print(event.Content())
    return nil
})

// Channel
events, errCh := client.Agents.ChatStreamChannel(ctx, params)
for event := range events {
    fmt.Print(event.Content())
}
if err := <-errCh; err != nil {
    log.Fatal(err)
}
```

`ChatStreamEvent` exposes `Content()`, `IsFinished()`, `Usage`, `FinishReason`, `ExternalToolCalls`, and `SideEffectsJSON` (facts, emotions, relationship updates).

### Chat (async with polling)

For chats that may run longer than your network can hold an SSE stream
open (Cloudflare/LB cuts at ~100s), queue the request and poll the
result endpoint. Cancelling the local context does **not** cancel the
server-side task — re-poll the same `processing_id` later if needed.

```go
// Fire-and-forget — returns ProcessingID immediately.
queued, _ := client.Agents.ChatAsync(ctx, sonzai.AgentChatParams{
    AgentID: "agent-id",
    ChatOptions: sonzai.ChatOptions{
        Messages: []sonzai.ChatMessage{{Role: "user", Content: "Plan my week."}},
        UserID:   "user-123",
        Provider: "openai",
        Model:    "gpt-4o",
    },
})

// Manual poll loop — recommended backoff: 1s → 2s → 4s, capped at 5s.
delay := time.Second
for {
    result, _ := client.Agents.PollChatResult(ctx, "agent-id", queued.ProcessingID)
    // Status: queued | running | complete | failed.
    // While running, Response carries partial assistant text and
    // Phase/Tool reflect the latest progressive-elaboration event.
    if result.IsTerminal() {
        fmt.Println(result.Response, string(result.SideEffects))
        break
    }
    time.Sleep(delay)
    if delay < 5*time.Second {
        delay *= 2
    }
}

// Convenience: queue + poll until terminal in one call.
result, err := client.Agents.ChatAsyncBlocking(ctx, sonzai.AgentChatParams{
    AgentID: "agent-id",
    ChatOptions: sonzai.ChatOptions{
        Messages: []sonzai.ChatMessage{{Role: "user", Content: "Plan my week."}},
        UserID:   "user-123",
    },
})
```

### Sync vs async memory recall (`memoryMode`)

Supplementary memory recall can be **synchronous** (blocks on recall, facts always land in the current turn) or **asynchronous** (races a deadline, slow hits spill to the next turn for lower first-token latency). Default is `sync`.

`memoryMode` is an agent-wide capability. You can set it at creation time or flip it later with `UpdateCapabilities`:

```go
// At creation
client.Agents.Create(ctx, sonzai.CreateAgentOptions{
    Name: "Aria",
    ToolCapabilities: &sonzai.AgentToolCapabilities{
        MemoryMode: "async",
    },
})

// Or flip an existing agent
client.Agents.UpdateCapabilities(ctx, "agent-id", sonzai.UpdateCapabilitiesOptions{
    MemoryMode: "async", // or "sync"
})

// Read the current mode
caps, _ := client.Agents.GetCapabilities(ctx, "agent-id")
fmt.Println(caps.MemoryMode)
```

`UpdateCapabilities` is PATCH-style — omitted fields are left unchanged. To skip the context engine entirely on a single chat (e.g. test paths), set `SkipContextBuild: true` in the chat options.

### Advanced chat options

```go
ChatOptions{
    Messages:             []sonzai.ChatMessage{...},
    UserID:               "user-123",
    UserDisplayName:      "Alex",
    SessionID:            "session-456",
    InstanceID:           "instance-789",     // parallel branch
    Provider:             "gemini",            // gemini | zhipu | volcengine | openrouter | custom
    Model:                "gemini-3.1-flash-lite",
    Language:             "en",
    Timezone:             "America/New_York",
    CompiledSystemPrompt: "You are a helpful assistant.",
    ToolCapabilities:     &sonzai.AgentToolCapabilities{WebSearch: true, RememberName: true},
    ToolDefinitions:      []sonzai.ToolDefinition{ /* external function calls */ },
    MaxTurns:             10,
    GameContext:          &sonzai.GameContext{ /* custom fields */ },
    SkillLevels:          map[string]int32{"negotiation": 5},
}
```

### Memory

```go
// Full memory tree
tree, _ := client.Agents.Memory.List(ctx, "agent-id", &sonzai.MemoryListOptions{
    UserID:          "user-123",
    IncludeContents: true,
    Limit:           100,
})
for _, node := range tree.Nodes {
    fmt.Printf("%s (importance: %.2f)\n", node.Title, node.Importance)
}

// Semantic search (cosine over fact embeddings when UserID is set)
results, _ := client.Agents.Memory.Search(ctx, "agent-id", sonzai.MemorySearchOptions{
    Query:  "favorite food",
    UserID: "user-123",
    Limit:  10,
})

// Timeline across a date range
timeline, _ := client.Agents.Memory.Timeline(ctx, "agent-id", &sonzai.MemoryTimelineOptions{
    UserID: "user-123",
    Start:  "2026-01-01",
    End:    "2026-03-01",
})

// Write a fact directly
fact, _ := client.Agents.Memory.CreateFact(ctx, "agent-id", sonzai.CreateFactOptions{
    UserID:     "user-123",
    Content:    "The user loves pizza",
    FactType:   "preference",
    Importance: 0.8,
    Entities:   []string{"pizza"},
})

// Update, delete, audit
client.Agents.Memory.UpdateFact(ctx, "agent-id", fact.FactID, sonzai.UpdateFactOptions{Importance: 0.9})
history, _ := client.Agents.Memory.GetFactHistory(ctx, "agent-id", fact.FactID)
client.Agents.Memory.DeleteFact(ctx, "agent-id", fact.FactID)

// Wisdom (agent-global) facts
client.Agents.Memory.GetWisdomAudit(ctx, "agent-id", fact.FactID)
client.Agents.Memory.DeleteWisdomFact(ctx, "agent-id", fact.FactID)

// Bulk create up to 1000 pre-formed facts (source_type="manual", no LLM extraction)
client.Agents.Memory.BulkCreateFacts(ctx, "agent-id", sonzai.BulkCreateFactsOptions{
    UserID: "user-123",
    Facts: []sonzai.BulkFactItem{
        {Content: "prefers espresso"},
        {Content: "based in Singapore", FactType: "location"},
    },
})

// Seed memories in bulk at agent creation
client.Agents.Memory.Seed(ctx, "agent-id", sonzai.SeedMemoriesOptions{
    UserID:   "user-123",
    Memories: []sonzai.SeedMemory{ /* ... */ },
})

// Reset all memory for a user
client.Agents.Memory.Reset(ctx, "agent-id", sonzai.MemoryResetOptions{UserID: "user-123"})
```

### Personality

```go
profile, _ := client.Agents.Personality.Get(ctx, "agent-id")
fmt.Println(profile.Profile.Big5.Openness)
fmt.Println(profile.Profile.Dimensions.Warmth)

// Recent personality shifts and significant moments
shifts, _ := client.Agents.Personality.GetRecentShifts(ctx, "agent-id")
moments, _ := client.Agents.Personality.GetSignificantMoments(ctx, "agent-id", 10)

// Per-user overlays (how the agent perceives a specific user)
overlays, _ := client.Agents.Personality.ListUserOverlays(ctx, "agent-id")
overlay, _ := client.Agents.Personality.GetUserOverlay(ctx, "agent-id", "user-123", sonzai.UserOverlayOptions{})
```

### Sessions & instances

`Sessions.Start` returns a `*Session` handle that bundles the identity tuple
(`AgentID`, `UserID`, `SessionID`, `InstanceID`) plus session-level
`Provider`/`Model` defaults. The handle drives the per-turn loop with one
fresh enriched context per turn — so the LLM you call out to (OpenAI,
Anthropic, Gemini, your own) sees an up-to-date mood, recalled facts,
and recent turns on every message.

```go
session, _ := client.Agents.Sessions.Start(ctx, "agent-id", sonzai.SessionStartOptions{
    UserID:    "user-123",
    SessionID: "session-456",
    Provider:  "gemini",                              // session-level default
    Model:     "gemini-3.1-flash-lite",       // (per-turn overrides OK)
})

// Per-turn loop: fetch enriched context, hand it to your LLM, submit the turn.
enriched, _ := session.Context(ctx, sonzai.ContextOptions{
    Query: "what's the user about to say?",
})
// ... build your prompt with `enriched`, call your LLM, get assistantReply ...

result, _ := session.Turn(ctx, sonzai.TurnOptions{
    Messages: []sonzai.TurnMessage{
        {Role: "user", Content: "what did we talk about last week?"},
        {Role: "assistant", Content: assistantReply},
    },
    // Prefetch the *next* enriched context in the same round-trip
    // so the next user message renders without a second fetch.
    FetchNextContext: &sonzai.FetchNextContext{Query: "anticipated next user message"},
})
fmt.Println(result.Mood)            // sync mood update (nil if none)
fmt.Println(result.ExtractionID)    // async fact-extraction job id
fmt.Println(result.NextContext)     // populated when FetchNextContext is set

// Poll deferred extraction (memory write-back) when you need to know it landed.
for {
    status, _ := session.TurnStatus(ctx, result.ExtractionID)
    if status.IsTerminal() { // "done" or "failed"
        break
    }
    time.Sleep(500 * time.Millisecond) // then back off
}

// End the session. Wait=true forces the CE pipeline to run synchronously
// (use in benchmarks/tests that query memory immediately after).
_ = session.End(ctx, sonzai.SessionEndOptions{
    TotalMessages:   10,
    DurationSeconds: 300,
    Wait:            true,
})
```

`TurnMessage` carries `ToolCallID` and `ToolCalls` for function-calling
turns; plain `ChatMessage` (used by `Chat` / `ChatStream`) is text-only.
Per-call `Provider`/`Model` on `TurnOptions` override the session
defaults; leave both empty to fall through.

#### Legacy void-style start/end

`Sessions.End` still accepts a void-style call when you don't need the
handle:

```go
client.Agents.Sessions.End(ctx, "agent-id", sonzai.SessionEndOptions{
    UserID:          "user-123",
    SessionID:       "session-456",
    TotalMessages:   10,
    DurationSeconds: 300,
})
```

#### Instances

```go
// Parallel agent instances for A/B testing or sandboxed forks
instance, _ := client.Agents.Instances.Create(ctx, "agent-id", sonzai.InstanceCreateOptions{Name: "Beta"})
client.Agents.Instances.Reset(ctx, "agent-id", instance.InstanceID)
client.Agents.Instances.Delete(ctx, "agent-id", instance.InstanceID)
```

### Context engine introspection

```go
mood, _          := client.Agents.GetMood(ctx, "agent-id", "user-123", "")
relationships, _ := client.Agents.GetRelationships(ctx, "agent-id", "user-123", "")
habits, _        := client.Agents.ListHabits(ctx, "agent-id", "user-123", "")
goals, _         := client.Agents.ListGoals(ctx, "agent-id", "user-123", "")
interests, _     := client.Agents.GetInterests(ctx, "agent-id", "user-123", "")
diary, _         := client.Agents.GetDiary(ctx, "agent-id", "user-123", "")
users, _         := client.Agents.GetUsers(ctx, "agent-id", nil)
breakthroughs, _ := client.Agents.GetBreakthroughs(ctx, "agent-id", "user-123", "")

// Single-call enriched context (memory, personality, mood, relationships, goals,
// plus recent_turns from this session for mid-session recall before consolidation runs)
enriched, _ := client.Agents.GetContext(ctx, "agent-id", sonzai.GetContextOptions{
    UserID: "user-123",
    Query:  "what did we discuss earlier about espresso?",
})
for _, t := range enriched.RecentTurns {
    fmt.Printf("[%s] %s: %s\n", t.Timestamp, t.Role, t.Content)
}

// Point-in-time personality snapshot
snapshot, _ := client.Agents.GetTimeMachine(ctx, "agent-id", sonzai.TimeMachineOptions{
    At:     "2026-01-15T00:00:00Z",
    UserID: "user-123",
})
```

### Custom state (scoped key-value)

```go
state, _ := client.Agents.CustomState.Create(ctx, "agent-id", sonzai.CustomStateCreateOptions{
    Key:         "player_level",
    Value:       map[string]any{"level": 15, "xp": 2400},
    Scope:       "user",       // or "global"
    ContentType: "json",
    UserID:      "user-123",
})

// Upsert by composite key
client.Agents.CustomState.Upsert(ctx, "agent-id", sonzai.CustomStateUpsertOptions{
    Key: "player_level", Scope: "user", UserID: "user-123",
    Value: map[string]any{"level": 16},
})

client.Agents.CustomState.GetByKey(ctx, "agent-id", sonzai.CustomStateGetByKeyOptions{
    Key: "player_level", Scope: "user", UserID: "user-123",
})
client.Agents.CustomState.DeleteByKey(ctx, "agent-id", sonzai.CustomStateDeleteByKeyOptions{
    Key: "player_level", Scope: "user", UserID: "user-123",
})
```

### Notifications

```go
pending, _ := client.Agents.Notifications.List(ctx, "agent-id", sonzai.NotificationListOptions{
    Status: "pending",
    UserID: "user-123",
    Limit:  20,
})
for _, n := range pending.Notifications {
    fmt.Printf("[%s] %s\n", n.CheckType, n.GeneratedMessage)
}

client.Agents.Notifications.Consume(ctx, "agent-id", "message-id")
history, _ := client.Agents.Notifications.History(ctx, "agent-id", 50)
```

### Knowledge base

```go
// Upload a document (PDF, markdown, etc.)
file, _ := os.Open("document.pdf")
defer file.Close()
doc, _ := client.Knowledge.UploadDocument(ctx, "project-id", "document.pdf", file, "application/pdf")

docs, _ := client.Knowledge.ListDocuments(ctx, "project-id", 100)
client.Knowledge.GetDocument(ctx, "project-id", doc.DocumentID)
client.Knowledge.DeleteDocument(ctx, "project-id", doc.DocumentID)

// Direct fact/graph insertion
client.Knowledge.InsertFacts(ctx, "project-id", sonzai.InsertFactsOptions{
    Source: "manual",
    Facts: []sonzai.InsertFactEntry{
        {EntityType: "person", Label: "Alice"},
    },
    Relationships: []sonzai.InsertRelEntry{
        {FromLabel: "Alice", ToLabel: "Bob", EdgeType: "knows"},
    },
})

// Cross-document semantic search
results, _ := client.Knowledge.Search(ctx, "project-id", sonzai.KBSearchOptions{
    Query: "how do I configure X?",
    Limit: 10,
})
for _, r := range results.Results {
    fmt.Printf("[%.2f] %s (type: %s)\n", r.Score, r.Label, r.NodeType)
}
```

### Voice (TTS, STT, live streaming)

```go
// Text-to-Speech
audio, _ := client.Agents.Voice.TTS(ctx, "agent-id", sonzai.TTSOptions{
    Text:      "Hello, how are you?",
    VoiceName: "Kore",
    Language:  "en-US",
})

// Speech-to-Text
transcript, _ := client.Agents.Voice.STT(ctx, "agent-id", sonzai.STTOptions{
    Audio:       base64.StdEncoding.EncodeToString(pcmBytes),
    AudioFormat: "pcm",
    Language:    "en-US",
})

// Live bidirectional voice (WebSocket, Gemini Live)
token, _ := client.Agents.Voice.GetToken(ctx, "agent-id", sonzai.VoiceTokenOptions{
    VoiceName: "Kore",
    Language:  "en-US",
    UserID:    "user-123",
})

stream, _ := client.Agents.Voice.Stream(ctx, token)
defer stream.Close()

stream.SendText("Hello!")
// or: stream.SendAudio(pcm16kHzMonoBytes)

for {
    event, err := stream.Recv()
    if err == io.EOF { break }
    switch event.Type {
    case "input_transcript":
        fmt.Println("User:", event.Text)
    case "output_transcript":
        fmt.Println("Agent:", event.Text)
    case "audio":
        playPCM(event.Audio) // 24kHz PCM
    case "turn_complete":
    case "session_ended":
        return
    }
}
```

### Evaluation & simulation

```go
import "github.com/sonz-ai/sonzai-go/eval"

// One-off evaluation over a conversation
result, _ := client.Eval.Evaluate(ctx, "agent-id", eval.EvaluateOptions{
    Messages:   []eval.Message{{Role: "user", Content: "Hello"}},
    TemplateID: "template-uuid",
})
fmt.Printf("Score: %.2f\n", result.Score)

// Streaming simulation
client.Eval.Simulate(ctx, "agent-id", eval.SimulateOptions{
    UserPersona: map[string]any{"name": "Alex", "background": "Student"},
    Config:      map[string]any{"max_sessions": 2, "max_turns_per_session": 5},
}, func(event eval.SimulationEvent) error {
    fmt.Printf("[%s] %s\n", event.Type, event.Message)
    return nil
})

// Fire-and-forget
ref, _ := client.Eval.SimulateAsync(ctx, "agent-id", eval.SimulateOptions{
    Config: map[string]any{"max_sessions": 2},
})
// Reconnect later (from_index supports resume)
client.Eval.Runs.StreamEvents(ctx, ref.RunID, 0, func(event eval.SimulationEvent) error {
    fmt.Printf("[%s] %s\n", event.Type, event.Message)
    return nil
})

// Combined simulation + evaluation
client.Eval.Run(ctx, "agent-id", eval.RunEvalOptions{
    TemplateID:       "template-uuid",
    SimulationConfig: map[string]any{"max_sessions": 2},
}, handler)

// Re-evaluate an existing run with a different template
client.Eval.ReEval(ctx, "agent-id", eval.ReEvalOptions{
    TemplateID:  "new-template-uuid",
    SourceRunID: "existing-run-uuid",
}, handler)

// Template & run management
tmpl, _ := client.Eval.Templates.Create(ctx, eval.CreateTemplateOptions{Name: "Empathy", ScoringRubric: "..."})
runs, _ := client.Eval.Runs.List(ctx, eval.ListRunsOptions{AgentID: "agent-id", Limit: 20})
run, _ := client.Eval.Runs.Get(ctx, "run-id")
client.Eval.Runs.Delete(ctx, "run-id")
```

### Webhooks

```go
// Register/update a webhook
resp, _ := client.Webhooks.Register(ctx, "agent.message.created", sonzai.WebhookRegisterOptions{
    WebhookURL: "https://example.com/hook",
    AuthHeader: "Bearer your-secret", // optional header added to deliveries
})
fmt.Println("signing secret:", resp.SigningSecret)

list, _       := client.Webhooks.List(ctx)
attempts, _   := client.Webhooks.ListDeliveryAttempts(ctx, "agent.message.created")
rotated, _    := client.Webhooks.RotateSecret(ctx, "agent.message.created")
client.Webhooks.Delete(ctx, "agent.message.created")

// Project-scoped variants
client.Webhooks.RegisterForProject(ctx, "project-id", "event.type", opts)
client.Webhooks.ListForProject(ctx, "project-id")
client.Webhooks.DeleteForProject(ctx, "project-id", "event.type")
```

### Webhook signature verification

Signatures are HMAC-SHA256 over `"{timestamp}.{payload}"`. Multiple `v1=` signatures are supported for secret rotation.

```go
func handler(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    sig := r.Header.Get("Sonzai-Signature")

    if err := sonzai.VerifyWebhookSignature(body, sig, webhookSecret); err != nil {
        switch {
        case errors.Is(err, sonzai.ErrInvalidSignature):
            http.Error(w, "bad signature", 401)
        case errors.Is(err, sonzai.ErrTimestampExpired):
            http.Error(w, "expired", 401)
        default:
            http.Error(w, "unauthorized", 401)
        }
        return
    }

    // Accept tighter/looser timestamp windows:
    sonzai.VerifyWebhookSignatureWithTolerance(body, sig, secret, 1*time.Minute)
}
```

## Error handling

```go
resp, err := client.Agents.Chat(ctx, params)
if err != nil {
    var (
        authErr      *sonzai.AuthenticationError
        notFoundErr  *sonzai.NotFoundError
        badReqErr    *sonzai.BadRequestError
        permErr      *sonzai.PermissionDeniedError
        rateErr      *sonzai.RateLimitError
        serverErr    *sonzai.InternalServerError
    )
    switch {
    case errors.As(err, &authErr):
        log.Fatal("invalid API key")
    case errors.As(err, &notFoundErr):
        log.Fatal("agent not found")
    case errors.As(err, &rateErr):
        if rateErr.RetryAfter != nil {
            log.Printf("rate limited, retry after %ds", *rateErr.RetryAfter)
        }
    case errors.As(err, &serverErr):
        log.Fatal("server error")
    }
}
```

All typed errors embed `sonzai.SonzaiError` (exposes `StatusCode` and `Message`).

## Benchmarks

Sonzai leads on **three** independent benchmarks (LoCoMo, LongMemEval,
SOTOPIA), running on the cheap end of the LLM stack — chat, judge, reader,
and partner agent all run on **Gemini 3.1 Flash Lite**. No frontier-model
arms race propping up the numbers; the lift is from the memory architecture.

### LoCoMo — long-term conversational memory (mem0's home turf)

10 peer-to-peer dialogues, 19–35 sessions each, 1540 QAs across 4 reasoning
categories. Run via mem0's published evaluation pipeline byte-for-byte
(their `ANSWER_PROMPT` + `ACCURACY_PROMPT`, dual-perspective ingest, dual
search) so numbers are directly comparable.

| Category | n | Sonzai (J) | mem0 (J, published) |
|---|---:|---:|---:|
| 1. single-hop | 282 | **0.720** | ~0.65 |
| 2. multi-hop | 321 | **0.723** | ~0.55 |
| 3. temporal reasoning | 96 | 0.531 | ~0.55 |
| 4. open-domain | 841 | **0.762** | ~0.71 |
| **Overall** | 1540 | **0.732** ✅ | ~0.67 |

Multi-hop is Sonzai's strongest category (**+~17 points** over mem0) — the
hardest LoCoMo bucket and the one mem0's graph variant typically claims its
lift on. Sonzai matches/beats without graph-specific machinery.

### LongMemEval — retrieval (MemPalace's home turf)

Sonzai beats MemPalace on the retrieval benchmark MemPalace was purpose-built to win:

| Metric | Sonzai | MemPalace (hybrid_v4) |
|---|---:|---:|
| R@G (overall recall) | **0.773** | 0.741 |
| R@1 (top-hit accuracy) | **0.800** | 0.770 |
| Recall@10, multi-session | **1.000** | 1.000 |

### SOTOPIA longitudinal — compounding across sessions

Sonzai's USP: agents that compound. Same agent, same partner, N sessions,
`advance_time` between each. Across 30 sessions Overall climbs from 8.44 → 9.56
(+1.13), and `memory_continuity` hits the rubric ceiling by session 10 — Sonzai's
identity model is producing accurate unprompted callbacks before a verbatim-retrieval
baseline has history to compete.

Full scores, methodology, per-question-type breakdown, and reproduction steps:

→ [sonzai-python/benchmarks/README.md](https://github.com/sonz-ai/sonzai-python/blob/main/benchmarks/README.md)

## Staying in sync with the production API

This SDK tracks `https://api.sonz.ai/docs/openapi.json`. A git pre-push hook
checks for drift; run `just install-hooks` once after cloning. To refresh the
committed spec snapshot, run `just sync-spec` and commit the diff.

## Documentation

- [Sonzai docs](https://sonz.ai/docs)
- [API reference](api.md)
- [Package docs on pkg.go.dev](https://pkg.go.dev/github.com/sonz-ai/sonzai-go)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT — see [LICENSE](LICENSE) for details.

Go 1.25 或更高；需在 Sonzai Dashboard 创建 API Key，可通过 SONZAI_API_KEY 环境变量或构造参数传入；BYOK 接口需 read:byok / write:byok 权限范围；模型服务商密钥与配额由使用方自备并直连；Sonzai 平台计费标准与 BYOK 服务费以官方为准，未经确认的价格不在此说明；托管服务可用区域、国内网络可达性与数据存储地域待核验。