インスタンス

同じエージェントを複数の分離されたコンテキスト（ワークスペース、部門、リージョン、テナント）にデプロイし、それぞれが独立した状態を持ちます。

インスタンスとは？

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

インスタンスデータモデル

instanceIdstring一意のインスタンス識別子

agentIdstring親エージェントID

namestring人間が読めるラベル

descriptionstring?オプションの説明

statusstring"active" または "inactive"

isDefaultboolean自動作成されたデフォルトインスタンスの場合はtrue

createdAtstringISO 8601タイムスタンプ

updatedAtstringISO 8601タイムスタンプ

← 評価とシミュレーションステート、ツール、プライミング→