Sonzai Docs

クイックスタート

マインドレイヤーで最初のAIエージェントを起動しましょう。

1. プロジェクトの作成

プロジェクトにアクセスし、 新しいプロジェクトを作成します。プロジェクトはエージェントをグループ化し、 認証用のAPIキーを提供します。

2. APIキーの取得

プロジェクト設定でAPIキーを生成します。このキーにより、 マインドレイヤーへのすべてのREST API呼び出しが認証されます。

# All requests require Bearer auth
Authorization: Bearer YOUR_API_KEY

3. エージェントの作成

エージェントを作成するには2つの方法があります：ビッグファイブスコアで パーソナリティ特性を明示的に定義するか、自然言語プロンプトから 生成するかです。

オプションA：プロンプトから生成

エージェントを自然言語で記述すると、プラットフォームがパーソナリティ、 略歴、シードメモリを自動生成します。

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

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

const agent = await client.generation.generateAndCreate({
  name: "Luna",
  description: "A cheerful and curious AI assistant who loves helping developers debug code. She's patient, witty, and always encouraging.",
  language: "en",
});

console.log(agent.agentId);        // auto-generated UUID
console.log(agent.personality);    // full Big5 profile derived from description

オプションB：ビッグファイブスコアで定義

精密な制御が必要な場合、明示的なビッグファイブスコアでエージェントを作成します。 プラットフォームがスコアから完全なパーソナリティプロファイル、発話パターン、 感情傾向を導出します。

import { Sonzai } from "@sonzai-labs/agents";
import { v5 as uuidv5 } from "uuid";

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

// Derive a stable UUID from your own entity ID
const MY_NAMESPACE = "your-uuid-namespace-here";
const agentId = uuidv5("support-agent-001", MY_NAMESPACE);

const agent = await client.agents.create({
  agentId,           // pass your own UUID — safe to repeat
  name: "Luna",
  gender: "female",
  big5: {
    openness:          0.75,
    conscientiousness: 0.60,
    extraversion:      0.80,
    agreeableness:     0.70,
    neuroticism:       0.30,
  },
  language: "en",
});

console.log(agent.agentId); // same UUID every time

冪等設計

エージェント作成は常に create-or-updateです。同じIDで 2回呼び出すと既存のエージェントが更新されます。エラーにならず、 重複も作成されません。これにより、起動コード、CIパイプライン、 プロビジョニングスクリプトで agents.create() を無条件に呼び出すことができます。

agentIdありサーバーがあなたのUUIDを直接使用します。推奨 — エージェントを 自分のエンティティID（エージェント、アシスタント、従業員）に リンクすることで、制御可能な決定論的マッピングを実現します。
agentIdなしサーバーがプロジェクトID + エージェント名からUUIDを導出します。 同じ名前は同じプロジェクト内で常に同じエージェントにマップされます。

4. エージェントとチャット

ストリーミングチャットを使用して、リアルタイムのAI応答を取得します。 プラットフォームがコンテキスト、記憶、状態の更新を自動的に処理します。

for await (const event of client.agents.chatStream("agent-id", {
  messages: [{ role: "user", content: "I had a great day hiking!" }],
  userId: "user-123",
})) {
  process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

サーバーサイド専用

SDKはサーバーサイド専用です。クライアントサイドの コードでAPIキーを公開しないでください。Webアプリの場合、バックエンドを 経由してプロキシしてください。詳細は インテグレーションガイド をご覧ください。

5. 時間経過の追跡

ダッシュボードにパーソナリティの変化、記憶の蓄積、ムードパターン、 関係性のダイナミクスが表示されます。ユーザーがインタラクションすると、 すべてのシステムが自動的に更新されます。

次のステップ

← 概要アーキテクチャ→