CRM、サポート、社内ツール、コンプライアンス向けのワークフロー対応AIエージェントを構築します。マルチインスタンス分離、Webhook駆動イベント、プロジェクトスコープのナレッジベース、評価実行、監査対応メモリを一括で実現します。

このクイックスタートは エンタープライズAIエージェント — ビジネスワークフローに組み込まれたエージェント — を構築する方向けです。CRMコパイロット、ティア1サポート、社内ナレッジアシスタント、商談資格審査ボット、コンプライアンスレビュアーなどが例として挙げられます。

作成するもの: ワークスペースごとに動作する商談資格審査エージェント。CRMからWebhook経由でディールイベントを受信し、製品ドキュメントを参照し、カスタムステートとしてワークフローステージを追跡し、各リリース前に評価ルーブリックに対して実行します。

使用するもの: マルチインスタンス分離、プロジェクトスコープのナレッジベース、カスタムステート、Webhook、ツール、評価実行。

1. プロジェクト、APIキー、Webhookシークレットを作成する

platform.sonz.ai でプロジェクトを作成し、APIキーとWebhook署名シークレットの両方を生成します。エンタープライズデプロイメントでは通常、環境（dev、staging、prod）ごとにAPIキーをスコープします。

export SONZAI_API_KEY=sk_...
export SONZAI_WEBHOOK_SECRET=whsec_...

2. エージェントを作成する

中立的でプロフェッショナルなパーソナリティを使用します。ムードのドリフトが返答に影響しないよう neuroticism を低く保ちます。

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

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

const agent = await client.agents.create({
name: "Pilot-SDR",
bio: "Pilot-SDR qualifies inbound leads, answers product questions, and hands off to humans when appropriate. Professional, concise, and never embellishes.",
big5: {
  openness: 0.5,
  conscientiousness: 0.9,
  extraversion: 0.55,
  agreeableness: 0.65,
  neuroticism: 0.15,
},
});

3. ワークスペースごとのインスタンスを作成する

各顧客ワークスペースに専用のインスタンスを割り当てます。instance_id = workspace-id にスコープされた記憶、カスタムステート、通知は完全に分離されます — マルチテナントSaaSとコンプライアンスにとって重要です。

const workspace = await client.agents.instances.create("agent-id", {
name: "acme-corp",
description: "Workspace for Acme Corp account",
});

スコープパターンとライフサイクルについてはマルチインスタンスを参照してください。

4. 製品ドキュメントをナレッジベースにアップロードする

ナレッジはプロジェクトスコープです — プロジェクト内のすべてのエージェントが同じコーパスを検索します。PDFをアップロードするか、構造化エンティティをプッシュするか、またはその両方を行います。

import { readFileSync } from "node:fs";

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

// Or push structured facts
await client.knowledge.insertFacts("project-id", {
entities: [
  { label: "Plan: Growth", properties: { price: 299, seats: 10 } },
  { label: "Plan: Enterprise", properties: { price: "custom", seats: "unlimited" } },
],
});

5. カスタムステートでワークフローステージを追跡する

すべてのディールやケースはステージ内に存在します。カスタムステートとして保存することで、エージェントはすべてのターンでそれを参照し、次に何をすべきかを推論できます。

await client.agents.customStates.create("agent-id", {
key: "deal_stage",
value: "discovery",
scope: "per-user-instance",
userId: "[email protected]",
instanceId: workspace.instance_id,
});

6. ハンドオフとCRM同期ツールを登録する

エンタープライズエージェントには、人間へのエスケープハッチとシステムオブレコードへの書き戻しが常に必要です。

await client.agents.sessions.setTools("agent-id", {
userId: "[email protected]",
instanceId: workspace.instance_id,
tools: [
  {
    name: "handoff_to_human",
    description: "Escalate this conversation to a human rep and stop the agent.",
    parameters: { type: "object", properties: { reason: { type: "string" } }, required: ["reason"] },
  },
  {
    name: "update_deal_stage",
    description: "Advance the deal to a new stage in the CRM.",
    parameters: {
      type: "object",
      properties: {
        stage: { type: "string", enum: ["discovery", "qualified", "demo", "proposal", "closed_won", "closed_lost"] },
      },
      required: ["stage"],
    },
  },
],
});

7. CRMイベント用のWebhookを登録する

CRMでディールのステージが変わったとき、そのイベントをSonzaiにプッシュします。エージェントは次のチャットターンでそれを「ワークフローイベント」として認識し、自然に反応します。

await client.webhooks.register("on_wakeup_ready", {
webhookUrl: "https://api.yourcorp.com/sonzai/wakeups",
});

await client.webhooks.register("on_recurring_event_due", {
webhookUrl: "https://api.yourcorp.com/sonzai/schedules",
});

すべてのWebhookリクエストはHMAC-SHA256で署名されています — 処理前にシークレットで検証してください。完全なイベントカタログ、リトライポリシー、検証例については Webhookと通知を参照してください。

8. チャットする

for await (const event of client.agents.chatStream({
agent: "agent-id",
userId: "[email protected]",
instanceId: workspace.instance_id,
messages: [{ role: "user", content: "Which plan fits a team of 12?" }],
})) {
const delta = event.choices?.[0]?.delta?.content;
if (delta) process.stdout.write(delta);
}

9. 評価実行でリリースをゲートする

プロンプトの変更や新しいエージェントバージョンをリリースする前に、評価ルーブリックに対して実行します。パーソナリティのドリフト、事実の正確性、ツール呼び出しの正確さを評点します。

// シミュレーション + 採点ランを開始し、すぐに戻る。
const ref = await client.agents.runEvalAsync("agent-id", {
templateId: "template_lead_qualification_v3",
simulationConfig: { turnsPerScenario: 6 },
});

// 評価が終わったらラン記録を読む（または streamEvents でライブ取得）。
const result = await client.evalRuns.get(ref.runId);
console.log(result.scoreOverall, result.scoresByCategory);

ルーブリックの構築とシミュレーションユーザーについては評価を参照してください。