Instances

Instances let you run a single agent across many isolated deployment contexts without cloning the agent itself. The shared parts — personality, memory, tools, voice — stay unified, while custom states are scoped per instance so a US-East workspace, an EU-West tenant, and a staging environment never see each other's data. Every agent gets a default instance for free; you only need explicit instances when the same AI Employee runs in parallel contexts that must not share runtime state.

What is an Instance?

An Instance is a deployment context for an agent. The agent itself (personality, memory, tools) is shared — but custom state is isolated per instance.

Agent "Luna"
├── Instance: default          ← used when instanceId is omitted
├── Instance: ws-us-east       ← US-East workspace
├── Instance: ws-eu-west       ← EU-West workspace
└── Instance: ws-staging       ← separate deployment

Each instance has its own:
• Global custom states (environment state, configuration)
• Per-user custom states scoped to this instance
• Isolated from other instances

List Instances

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

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

const instances = await client.agents.instances.list("agent-id");

for (const inst of instances) {
console.log(inst.instanceId, inst.name, inst.isDefault, inst.status);
}

Create an Instance

const instance = await client.agents.instances.create("agent-id", {
name: "Workspace US-East",
description: "US-East production workspace",
});

console.log(instance.instance_id); // store this

Get an Instance

const instance = await client.agents.instances.get(
"agent-id",
"instance-id",
);

console.log(instance.name, instance.status, instance.isDefault);

Update an Instance

await client.agents.instances.update("agent-id", "instance-id", {
name: "Workspace US-East (Production)",
status: "active",    // "active" | "inactive"
});

Reset an Instance

Clears all custom state data for an instance without deleting it. Useful for resetting an environment between sessions.

// Wipes all custom states scoped to this instance
await client.agents.instances.reset("agent-id", "instance-id");

Delete an Instance

await client.agents.instances.delete("agent-id", "instance-id");

Using Instances in Chat

Pass instanceId to chat calls to scope state reads to that instance. The agent will see global custom states for that instance and per-user states scoped to it.

for await (const event of client.agents.chatStream({
agent: "agent-id",
messages: [{ role: "user", content: "What's the current status?" }],
userId:     "user-123",
instanceId: "ws-us-east",      // scopes state reads to this instance
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

Instance Data Model

• instanceId (string): Unique instance identifier
• agentId (string): Parent agent ID
• name (string): Human-readable label
• description (string?): Optional description
• status (string): "active" or "inactive"
• isDefault (boolean): True for the auto-created default instance
• createdAt (string): ISO 8601 timestamp
• updatedAt (string): ISO 8601 timestamp