Build With Full Control
Scoped state management, multi-instance agents, custom tool calling, and built-in capabilities. Everything you need to build production AI systems.
State Management
Key-Value State at Every Scope
Persist arbitrary data scoped to global, per-user, or per-instance levels. Store JSON, text, or binary data. Upsert by composite key, query by scope, and manage state across your entire agent fleet. Perfect for onboarding flows, feature flags, user preferences, and game progression.
// Store user-scoped state
client.Agents.CustomState.Upsert(ctx, agentID,
sonzai.CustomStateUpsertOptions{
Key: "onboarding_step",
Value: "3",
Scope: "user",
UserID: "user_123",
ContentType: "text",
},
)
// Store global config as JSON
client.Agents.CustomState.Upsert(ctx, agentID,
sonzai.CustomStateUpsertOptions{
Key: "pricing_tiers",
Value: map[string]any{"basic": 9.99, "pro": 29.99},
Scope: "global",
ContentType: "json",
},
)
// Read state by composite key
state, _ := client.Agents.CustomState.GetByKey(ctx, agentID,
sonzai.CustomStateGetByKeyOptions{
Key: "onboarding_step",
Scope: "user",
UserID: "user_123",
},
)get(agent, "onboarding_step", scope:user, user_123) → 3Instances
One Agent, Many Contexts
Run separate instances of the same AI employee across different contexts — regions, customer segments, game worlds, or timelines. Each instance maintains its own memory, state, and personality while sharing the same base configuration. Reset, update, or delete instances independently.
// Create isolated instances for different contexts
euInstance, _ := client.Agents.Instances.Create(ctx, agentID,
"EU Support", "Instance for European customers",
)
apacInstance, _ := client.Agents.Instances.Create(ctx, agentID,
"APAC Support", "Instance for Asia-Pacific customers",
)
// Chat within a specific instance
response, _ := client.Agents.Chat(ctx, agentID,
sonzai.ChatOptions{
UserID: "user_123",
Message: "What are your opening hours?",
InstanceID: euInstance.InstanceID,
},
)
// Reset an instance without affecting others
client.Agents.Instances.Reset(ctx, agentID,
euInstance.InstanceID,
)Tool Calling
Give Your AI Custom Capabilities
Define custom tools with typed parameters and attach them to sessions. Your AI employees can call external APIs, query databases, trigger workflows, or perform any action you define. Tools are scoped per-session so you control exactly what's available in each context.
// Start a session
session, _ := client.Agents.Sessions.Start(ctx, agentID,
sonzai.SessionStartOptions{
UserID: "user_123",
SessionID: "session_abc",
},
)
// Attach custom tools to the session
client.Agents.Sessions.SetTools(ctx, agentID, session.SessionID,
sonzai.SessionToolsOptions{
Tools: []sonzai.ToolDefinition{
{
Name: "check_order_status",
Description: "Look up a customer's order by ID",
Parameters: map[string]any{
"type": "object",
"properties": map[string]any{
"order_id": map[string]any{
"type": "string",
"description": "The order ID to look up",
},
},
"required": []string{"order_id"},
},
},
{
Name: "schedule_callback",
Description: "Schedule a callback for the customer",
Parameters: map[string]any{
"type": "object",
"properties": map[string]any{
"time": map[string]any{
"type": "string",
"description": "ISO 8601 datetime",
},
},
},
},
},
},
)Built-In Tools
Batteries Included
Enable powerful built-in capabilities with a single flag — web search, name remembering, image generation, and inventory management. No integration work needed. Toggle them on per-agent or per-session.
// Enable built-in tools when creating an agent
agent, _ := client.Agents.Create(ctx, sonzai.CreateAgentOptions{
DisplayName: "Sales Assistant",
Bio: "Helpful sales assistant for an e-commerce store",
ToolCapabilities: &sonzai.AgentToolCapabilities{
WebSearch: true, // Can search the web
RememberName: true, // Remembers user names
ImageGeneration: true, // Can generate images
Inventory: true, // Can manage user inventories
},
})
// Or toggle tools on an existing agent
client.Agents.Update(ctx, agentID, sonzai.UpdateAgentOptions{
ToolCapabilities: &sonzai.AgentToolCapabilities{
WebSearch: true,
RememberName: true,
ImageGeneration: false,
Inventory: true,
},
})