パターン 1: マネージドエージェントランタイム

アプリは client.agents.chat（または sessions.start → チャットターン → sessions.end の明示的なセッション）を呼ぶだけで、Sonzai がエージェントの アイデンティティからシステムプロンプトを組み立て、関連メモリを呼び出し、 LLM を実行し、トークンをストリーミングで返し、登録済みツールを実行し、 状態を更新します — すべて 1 回の呼び出しで完結します。 もっともコード量が少ないパターンで、チャットコンパニオン、サポート エージェント、Sonzai がエージェントループ全体を所有しても問題ない用途の 既定の選択肢です。

使うべき時

• 1 ターンあたり HTTP 呼び出しを 1 回にし、メモリ周りの配管コードをゼロに したい。
• LLM プロバイダの選定を Sonzai に任せる（あるいは引数でオーバーライド する）形でかまわない。
• パーソナリティ、ムード、メモリ、ボイス、KB 検索、プロアクティブ通知が 「そのまま動く」状態を、自分でオーケストレーションせずに得たい。

切り替えるべき時

• 自前 LLM が必須 — パターン 4: スタンドアローン・リアルタイム に切り替え。
• 会話がプラットフォーム外で起きる（録音、トランスクリプト、バッチ取り 込み）— パターン 5: スタンドアローン・バッチ に切り替え。
• Claude Desktop / Cursor / MCP 互換 IDE で動かす — パターン 2: MCP に切り替え。
• OpenClaw を使っている — パターン 3: OpenClaw に切り替え。

アーキテクチャ

┌─────────────┐     ┌───────────────────────────────────┐
│  Your App   │     │            Sonzai                 │
└──────┬──────┘     └──────────────────┬────────────────┘
     │                                │
     │  agents.chat({ messages })     │
     │───────────────────────────────>│  • assemble context
     │                                │     (memory, mood,
     │                                │      personality, KB,
     │                                │      relationship)
     │                                │  • run LLM (your choice
     │                                │      of provider/model)
     │                                │  • execute registered
     │                                │      tools (if any)
     │  <── SSE stream ───────────────│  • write back: facts,
     │      tokens + done             │      mood, personality,
     │                                │      goals, habits
     │                                │
     │  (optional) sessions.end       │
     │───────────────────────────────>│  • consolidate, dedup,
     │                                │      diary, clustering

エンドツーエンドの例

最小構成：明示的にセッションを開き、ストリーミングチャットを駆動し、 セッションを終了します。

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

const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const AGENT_ID  = "agent-uuid";
const USER_ID   = "user-123";
const SESSION_ID = crypto.randomUUID();

// 1. Start an explicit session (optional — agents.chat will auto-create one
//    if you don't, but explicit sessions let you scope tools and lifecycle).
await sonzai.agents.sessions.start(AGENT_ID, {
userId:    USER_ID,
sessionId: SESSION_ID,
});

// 2. Drive turns. Sonzai owns context assembly, the LLM call, tool exec,
//    and writeback. You stream the reply straight to your UI.
for await (const event of sonzai.agents.chatStream({
agent:     AGENT_ID,
sessionId: SESSION_ID,
userId:    USER_ID,
messages:  [{ role: "user", content: "Hi! How's your day going?" }],
language:  "en",
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

// 3. End the session — triggers fact extraction + consolidation.
await sonzai.agents.sessions.end(AGENT_ID, {
userId:        USER_ID,
sessionId:     SESSION_ID,
totalMessages: 2,
});

次に読む