实例

将同一智能体部署到多个隔离的上下文中 — 工作区、部门、地区或租户 — 每个都有独立的状态。

什么是实例？

Instance 是智能体的一个部署上下文。智能体本身（人格、记忆、工具）是共享的 — 但自定义状态按实例隔离。

智能体 "Luna"
├── 实例: default          ← 省略 instanceId 时使用
├── 实例: ws-us-east       ← 美东工作区
├── 实例: ws-eu-west       ← 欧西工作区
└── 实例: ws-staging       ← 独立部署

每个实例拥有:
  • 全局自定义状态（环境状态、配置）
  • 按实例隔离的用户级自定义状态
  • 与其他实例完全隔离

默认实例

每个智能体都有一个默认实例。如果您不传 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); // 存储此值

获取实例

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"
});

重置实例

清除实例的所有自定义状态数据，但不删除实例本身。适用于在会话之间重置环境。

// 清除此实例范围内的所有自定义状态
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",      // 将状态读取限定到此实例
})) {
  process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

实例数据模型

instanceIdstring唯一实例标识符

agentIdstring父级智能体 ID

namestring人类可读标签

descriptionstring?可选描述

statusstring"active" 或 "inactive"

isDefaultboolean自动创建的默认实例为 true

createdAtstringISO 8601 时间戳

updatedAtstringISO 8601 时间戳

← 评估与模拟状态、工具与引导→