リアルタイムチャットライフサイクル：メッセージ送信、応答ストリーミング、プラットフォームによるエージェント状態の自動更新。

セッションフロー

すべての会話はシンプルな3ステップのライフサイクルに従います。

1. チャットリクエストを送信   — エージェントID・ユーザーID・アプリケーションコンテキスト・メッセージを渡す
2. ストリームを受信            — トークンをリアルタイムでユーザーにレンダリング
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);

チャット（ストリーミング）

より応答性の高い体験のためにトークンが届き次第ストリームします。内部ではサーバー送信イベント（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

1回のチャット呼び出しでエージェントが生成するアシスタントターンの最大数を制限します。エージェントがフォローアップメッセージを送る可能性のあるマルチメッセージ応答を制御するのに便利です。

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

プロダクトの機能に基づいてオプトインツールを有効化します。メモリと状態ツールはプラットフォームが管理します。

実践ガイド

チャットの形式は3つのオーディエンスで同じです——違うのは何を渡すか、そしてストリームをどう処理するかです。

常にストリームを使いましょう。 コンパニオンは生き生きとしているべきです。トークンが届き次第レンダリングし、まとめて表示しないでください。

マルチメッセージ返信に maxTurns を使用。 Lunaに2〜3の短いメッセージを連続して送らせたい場合（コンパニオンチャットとしてより自然）、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 は渡さないでください。 ほとんどのコンパニオンは1対1です。デフォルトのスコープはユーザーごとであり、それが望ましい形です。

会話

On this page