Sonzai Docs

Instances

Deploy the same agent into multiple isolated contexts — workspaces, departments, regions, or tenants — each with their own independent 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

Default Instance

Every agent has a default instance. If you don't pass instanceId to chat or state operations, the default instance is used. You only need multiple instances if you run the same agent in parallel isolated contexts.

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.instanceId); // 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

instanceIdstringUnique instance identifier
agentIdstringParent agent ID
namestringHuman-readable label
descriptionstring?Optional description
statusstring"active" or "inactive"
isDefaultbooleanTrue for the auto-created default instance
createdAtstringISO 8601 timestamp
updatedAtstringISO 8601 timestamp
← Knowledge BaseStates, Tools & Priming→