实时聊天生命周期：发送消息、流式接收响应，让平台自动更新智能体状态。

会话流程

每段对话遵循简单的三步生命周期：

1. 发送聊天请求   — 传入智能体 ID、用户 ID、应用上下文和消息
2. 接收流式响应  — 实时将 token 渲染给用户
3. 平台自动更新  — 记忆、情绪、关系和人格自动演化

聊天（非流式）

对于简单的请求-响应流程，使用标准聊天方法。

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

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

const response = await client.agents.chat({
agent: "agent-id",
messages: [{ role: "user", content: "Hello!" }],
userId: "user-123",
language: "en",
});

console.log(response.content);

聊天（流式）

以流式方式接收 token，获得更流畅的体验。底层使用服务器发送事件（SSE）。

for await (const event of client.agents.chatStream({
agent: "agent-id",
messages: [{ role: "user", content: "Tell me a story" }],
userId: "user-123",
language: "en",
timezone: "America/New_York",
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

SSE 格式

REST 端点发送 OpenAI 兼容的 SSE 数据块。每行以 data: 开头。流以 data: [DONE] 结束。

聊天选项

max_turns

限制智能体在单次聊天调用中产生的助手轮次数量。适用于控制多消息响应——智能体可能会发送后续消息。

for await (const event of client.agents.chatStream({
agent: "agent-id",
messages: [{ role: "user", content: "Tell me about your week" }],
userId: "user-123",
maxTurns: 3,   // 智能体最多产生 3 条助手消息
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

默认行为

未设置 max_turns 时，智能体根据上下文决定发送多少条消息。如果始终想要单条响应，将其设置为 1。

应用上下文

每次请求传入应用状态，让智能体在对话中可以引用它。平台不缓存此状态——每次聊天调用都要发送。

// 将每次请求的状态嵌入 compiledSystemPrompt——平台不缓存它。
const appState = [
"Department: Engineering",
"Current task: Q2 roadmap review",
"Open tickets: 12",
"Role: Senior Developer",
].join("\n");

for await (const event of client.agents.chatStream({
agent:    "agent-id",
messages: [{ role: "user", content: "What should I do next?" }],
userId:   "user-123",
compiledSystemPrompt: appState,
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

平台管理的状态更新

每次交互后，平台自动处理以下内容。无需额外的 API 调用。

记忆提取：从对话中提取事实、事件和承诺。
情绪更新：检测到的情感主题推动情绪维度变化。
人格演化：基于交互模式的渐进式大五变化。
习惯追踪：反复出现的模式成为被追踪的习惯。
关系更新：更新化学反应和关系叙事。
目标进展：记录活跃目标上的进展。

多智能体对话

使用对话 API 编排多个智能体之间的对话，或让智能体在没有直接用户消息的情况下响应共享场景上下文。

const response = await client.agents.dialogue("agent-id", {
userId: "user-123",
messages: [
  { role: "user", content: "Tell the group about your weekend plans" },
],
sceneGuidance: "A casual team standup meeting",
});

console.log(response.content);

工具调用

内部工具（记忆、状态）自动运行。你只需为终端用户能力配置选择性启用的工具：

选择性启用工具

generate_image：根据文本提示生成图像
generate_video：根据文本提示生成视频
generate_sound：生成音效
generate_music：生成背景音乐
generate_tts：文本转语音转换

通过 SDK 启用

for await (const event of client.agents.chatStream({
agent: "agent-id",
messages: [{ role: "user", content: "Show me a sunset!" }],
userId: "user-123",
tools: ["generate_image"],
})) {
if (event.type === "image") {
  console.log("Generated image:", event.imageUrl);
}
}

根据你产品的能力启用选择性工具。记忆和状态工具由平台管理。

实际应用

三类受众的聊天形式相同——区别在于你传入什么以及如何处理流式数据。

始终使用流式。 伴侣应该感觉是有生命的。token 一到就渲染，永远不要攒着一起发。

用 maxTurns 实现多消息回复。 如果你希望 Luna 连发两三条短消息（对伴侣聊天来说更自然），将 maxTurns 从默认值 1 调高。流式数据会发出独立的消息边界——在你的 UI 中将它们显示为独立气泡。

for await (const event of client.agents.chatStream({
  agent: "agent-id",
  userId: "user-123",
  messages: [{ role: "user", content: "I'm having a rough day." }],
  maxTurns: 3,
})) {
  if (event.type === "message_boundary") newBubble();
  else renderDelta(event);
}

不要传 instanceId。 大多数伴侣是一对一的；默认的每用户作用域正是你需要的。

对话

On this page