ビッグファイブパーソナリティ、4次元ムード、関係性追跡、プロアクティブなアウトリーチを持つキャラクター主導のエージェントを構築します。このガイドではコンパニオンの完全なスタックをエンドツーエンドで解説します。

このクイックスタートは AIコンパニオン — 本物のパーソナリティ、豊かな内面、そして時間とともに進化するユーザーとの関係性を持つキャラクター — を構築する方向けです。AIキャラクター、VTuber、パーソナルコンパニオン、ストーリーNPCなどが例として挙げられます。

作成するもの: 温かく好奇心旺盛なコンパニオンの Luna。会話を記憶し、本物の関係性を築き、適切なタイミングでプロアクティブに連絡します。

使用するもの: ビッグファイブパーソナリティ、4次元ムード、階層的記憶、関係性追跡、プロアクティブウェイクアップ、そして（任意で）ボイス。

1. APIキーを取得する

platform.sonz.ai でプロジェクトを作成し、APIキーを生成します。

Authorization: Bearer sk_your_api_key

2. 説明からエージェントを生成する

最も手軽な方法：自然言語でキャラクターを説明し、プラットフォームにパーソナリティ、話し方のパターン、シードメモリを推測させます。

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

const client = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });

const agent = await client.agents.generation.generateAndCreate({
name: "Luna",
description: "Luna is a warm, creative dreamer who speaks poetically. She loves stargazing, coffee shops at 2am, and asking the question beneath the question.",
language: "en",
});

console.log(agent.agent_id);
console.log(agent.personality); // full Big5 profile derived from the description

キャラクターを明示的に定義することもできます — ビッグファイブスコア、話し方のパターン、詳細な略歴を設定します。エージェント生成を参照してください。

3. 関係性をプライムする

最初のチャットの前に、このユーザーが誰かをエージェントに伝えます。プライミングにより初期の記憶ツリーが作成され、エージェントはこれらの事実を自然に参照します。

await client.agents.priming.primeUser("agent-id", "user-123", {
displayName: "Sam",
interests: ["astronomy", "lo-fi music", "photography"],
context: "Sam is a night-owl grad student who tends to overthink. They came to Luna after a tough week.",
});

4. チャット — コンパニオンではストリーミングが標準

コンパニオンは生き生きと感じられる必要があります。常にストリーミングを使用してください。

for await (const event of client.agents.chatStream({
agent: "agent-id",
userId: "user-123",
messages: [{ role: "user", content: "I can't sleep again." }],
})) {
const delta = event.choices?.[0]?.delta?.content;
if (delta) process.stdout.write(delta);
}

ターン終了後、Sonzai は自動的に以下を処理します：

新しい事実、イベント、コミットメントを記憶として抽出します。
会話の感情的な内容に基づいてムード（幸福感、エネルギー、落ち着き、愛着）を更新します。
インタラクションからキャラクターの方向性に関する安定した情報が得られた場合、ビッグファイブ特性を微調整します。
関係性の状態（ラブスコア、相性、インタラクション連続記録）を更新します。

これらの管理は不要です。

5. ムードと関係性の状態を読み取る

UI を駆動するために — 小さなムードインジケーター、関係レベルゲート、相性に応じて変化するテーマなど — 現在の状態を取得します。

// 現在のムード（4次元）— パーソナリティとは別に取得
const mood = await client.agents.getMood("agent-id", { userId: "user-123" });
console.log(mood.happiness, mood.energy, mood.calmness, mood.affection);

// 現在のパーソナリティプロファイル（ビッグファイブ、次元、話し方のパターン）
const personality = await client.agents.personality.get("agent-id");
console.log(personality.profile.big5);

6. Luna から先に連絡させる

プロアクティブウェイクアップは、コンパニオンをチャットボットと区別する機能です。プラットフォームは関係性コンテキストに基づいて自動的にスケジュールします — または明示的にトリガーすることもできます。

// Poll periodically (or register a webhook).
const pending = await client.agents.notifications.list("agent-id", {
userId: "user-123",
status: "pending",
});

for (const n of pending.notifications) {
// Render n.content in your UI; mark consumed when shown.
await client.agents.notifications.consume("agent-id", n.notificationId);
}

7. Luna にボイスを与える（任意）

グローバルカタログからボイスを選択するかクローンして、TTSまたは双方向オーディオをストリーミングします。完全な機能はボイスを参照してください。

const voices = await client.voices.list({ language: "en" });
await client.agents.update("agent-id", { voiceId: voices[0].voiceId });

次のステップ

パーソナリティ

ビッグファイブモデル、特性、進化、話し方のパターン。

感情とムード

4次元ムードモデル、減衰、イベント駆動のシフト。

記憶

階層的記憶ツリー：事実、イベント、コミットメント、サマリー。

会話

ストリーミング、セッション、マルチターンフロー。

ボイス

TTS、STT、双方向ストリーミング、ボイスクローニング。

プロアクティブウェイクアップ

スケジュールされたアウトリーチのトリガーと配信方法。

現在のSDKバージョン: TypeScript 1.1.3 · Python 1.1.4 · Go 1.2.0 (as of 2026-04-17)

AIコンパニオン — クイックスタート