インスタンス
同じエージェントを複数の分離されたコンテキスト（ワークスペース、部門、リージョン、テナント）にデプロイし、それぞれが独立した状態を持ちます。
インスタンスとは？
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デフォルトインスタンス
すべてのエージェントにデフォルトインスタンスがあります。チャットや状態操作でinstanceIdを渡さない場合、デフォルトインスタンスが使用されます。同じエージェントを並行して分離されたコンテキストで実行する場合のみ、複数のインスタンスが必要です。
インスタンスの一覧
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);
}インスタンスの作成
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インスタンスの取得
const instance = await client.agents.instances.get(
"agent-id",
"instance-id",
);
console.log(instance.name, instance.status, instance.isDefault);インスタンスの更新
await client.agents.instances.update("agent-id", "instance-id", {
name: "Workspace US-East (Production)",
status: "active", // "active" | "inactive"
});インスタンスのリセット
インスタンスを削除せずにすべてのカスタム状態データをクリアします。セッション間で環境をリセットするのに便利です。
// Wipes all custom states scoped to this instance
await client.agents.instances.reset("agent-id", "instance-id");インスタンスの削除
await client.agents.instances.delete("agent-id", "instance-id");チャットでのインスタンス使用
チャット呼び出しでinstanceIdを渡して、そのインスタンスへの状態読み取りをスコープします。エージェントはそのインスタンスのグローバルカスタム状態とスコープされたユーザーごとの状態を参照します。
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 ?? "");
}インスタンスデータモデル
instanceId(string): 一意のインスタンス識別子agentId(string): 親エージェントIDname(string): 人間が読めるラベルdescription(string?): オプションの説明status(string): "active" または "inactive"isDefault(boolean): 自動作成されたデフォルトインスタンスの場合はtruecreatedAt(string): ISO 8601タイムスタンプupdatedAt(string): ISO 8601タイムスタンプ