ユーザーを記憶し、ツールを使用し、ナレッジベースを活用するタスク指向エージェントを構築します。タスクエージェントにパーソナリティやムードは必須ではありません。このガイドでは何を設定し、何をスキップできるかを説明します。

このクイックスタートは AIエンプロイー または パーソナルAI — ユーザーの業務を支援するタスク指向エージェント — を構築する方向けです。サポートエンジニア、営業開発担当者、受信トレイアシスタント、オンボーディングガイドなどが例として挙げられます。

作成するもの: カスタマーサポートエージェント。(1) セッションをまたいで各ユーザーを記憶し、(2) カスタムツールでチケット作成と注文ステータス照会が可能で、(3) ナレッジベースから製品に関する質問に回答します。

スキップできるもの: 感情システム。ムードはバックグラウンドで動作しますが、明示的にオプトインしない限り返答に影響しません。パーソナリティは最小限に抑えられます — プロフェッショナルなトーンプロファイルで十分です。

1. プロジェクトを作成してAPIキーを取得する

platform.sonz.ai でプロジェクトを作成し、APIキーを生成します。すべてのリクエストはBearer認証を使用します：

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.create({
name: "Atlas",
bio: "Atlas is a calm, precise support engineer who answers product questions and handles tickets.",
big5: {
  openness: 0.55,
  conscientiousness: 0.85,
  extraversion: 0.5,
  agreeableness: 0.7,
  neuroticism: 0.2,
},
});

console.log(agent.agent_id);

3. ユーザーごとのインスタンスを作成する

複数のエンドユーザーにサービスを提供するタスクエージェントでは、インスタンス を使用して各ユーザーが1つのエージェント定義のもとで独立したメモリスコープを持つようにします。

const instance = await client.agents.instances.create("agent-id", {
name: "user-42",
description: "Support context for user 42",
});

instance_id = "user-42" にスコープされたすべての記憶、カスタムステート、通知は、他のユーザーのコンテキストから完全に隔離されます。

4. エージェントがユーザーについて知っている情報をシードする

ユーザーの事実を事前にロードして、エージェントの最初の返答からコンテキストが反映されるようにします — コールドスタートを排除します。

await client.agents.memory.seed("agent-id", {
userId: "user-42",
memories: [
  { text: "User's name is Priya Kapoor.", factType: "fact" },
  { text: "Priya is on the Enterprise plan, renewed 2026-03-15.", factType: "fact" },
  { text: "Priya reported a billing issue last week (ticket #4821, resolved).", factType: "event" },
],
});

5. カスタムツールを登録する

ツールを使用すると、LLMが推論中にバックエンドを呼び出せます。Sonzaiはツールを実行しません — ツール呼び出しを返し、バックエンドが実行して、次のターンで結果を渡します。

await client.agents.sessions.setTools("agent-id", {
userId: "user-42",
tools: [
  {
    name: "create_ticket",
    description: "Create a support ticket for the user.",
    parameters: {
      type: "object",
      properties: {
        subject: { type: "string" },
        priority: { type: "string", enum: ["low", "normal", "high"] },
      },
      required: ["subject"],
    },
  },
  {
    name: "lookup_order",
    description: "Fetch the latest order status by order ID.",
    parameters: {
      type: "object",
      properties: { orderId: { type: "string" } },
      required: ["orderId"],
    },
  },
],
});

6. ナレッジベースをアップロードする

製品ドキュメント、社内FAQ、またはランブックをエージェントに提供します。ナレッジベースはプロジェクトスコープです — プロジェクト内のすべてのエージェントが検索できます。

import { readFileSync } from "node:fs";

const buf = readFileSync("./product-manual.pdf");
await client.knowledge.uploadDocument("project-id", "product-manual.pdf", buf, "application/pdf");

knowledge_search ケイパビリティが有効なエージェントは、会話中に自動的にナレッジベースを検索します。

7. チャットする

レスポンスをストリーミングします。エージェントは記憶、ナレッジ、ツールを自動的に使用します。

for await (const event of client.agents.chatStream({
agent: "agent-id",
userId: "user-42",
instanceId: instance.instance_id,
messages: [{ role: "user", content: "Hi, did my latest invoice go through?" }],
})) {
const delta = event.choices?.[0]?.delta?.content;
if (delta) process.stdout.write(delta);
}

返答後、記憶の抽出が自動的に実行されます — 何もしなくてもエージェントはやり取りの内容を記憶します。

8. プロアクティブ通知をポーリングする（任意）

エージェントはフォローアップをスケジュールできます — 例：「チケット#4821について明日確認する」。通知キューを定期的にポーリングするか、webhookを登録してください。

const pending = await client.agents.notifications.list("agent-id", { userId: "user-42", status: "pending" });

次のステップ

記憶

記憶の抽出、シード、検索のエンドツーエンドの仕組み。

カスタムステートとツール

構造化ステートとツール定義の登録。

ナレッジベース

ドキュメントのアップロード、構造化ファクトのプッシュ、エンティティ検索。

マルチインスタンス

ユーザーごと・ワークスペースごとの分離パターン。

Webhook

タスク完了、通知、SLAに対応したリアルタイムイベントコールバック。

完全なインテグレーションガイド

すべてのSDKサーフェスとインテグレーションパスの詳細。

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

AIエンプロイーとパーソナルAI — クイックスタート