Build a workflow-aware AI agent for CRM, support, internal tools, or compliance. Multi-instance isolation, webhook-driven events, project-scoped knowledge base, eval runs, and audit-ready memory — in one pass.

This quickstart is for building enterprise AI agents — agents embedded into business workflows. Think: CRM copilots, tier-1 support, internal knowledge assistants, sales-qualification bots, compliance reviewers.

What you'll build: a sales-qualification agent that runs per-workspace, receives deal events from your CRM via webhook, pulls from your product docs, tracks workflow stage as custom state, and runs against eval rubrics before each release.

What you'll use: multi-instance isolation, project-scoped knowledge base, custom states, webhooks, tools, and evaluation runs.

1. Create project, API key, webhook secret

In platform.sonz.ai, create a project and generate both an API key and a webhook signing secret. Enterprise deployments usually scope API keys per environment (dev, staging, prod).

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

2. Create the agent

Use a neutral, professional personality. Keep neuroticism low to avoid mood drift affecting replies.

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. Create per-workspace instances

Each customer workspace gets its own instance. Memory, custom state, and notifications scoped to instance_id = workspace-id stay isolated — critical for multi-tenant SaaS and compliance.

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

See Multi-Instance for scoping patterns and lifecycle.

4. Upload product docs to the knowledge base

Knowledge is project-scoped — every agent in the project searches the same corpus. Upload PDFs, push structured entities, or both.

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. Track workflow stage with custom state

Every deal or case lives in a stage. Store it as custom state so the agent sees it on every turn and can reason about what comes next.

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

6. Register handoff and CRM-sync tools

Enterprise agents always need an escape hatch to humans plus write-back into your system of record.

await client.agents.sessions.setTools("agent-id", "session-id", [
{
  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. Register webhooks for CRM events

Push platform events into your stack. Each webhook subscribes to one event type — register the events you care about. The agent sees these as "workflow events" and reacts naturally on the next turn.

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",
});

Every webhook request is signed with HMAC-SHA256 — verify before acting. See Webhooks & Notifications for the full event catalog, retry policy, and verification example.

8. Chat

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. Gate releases on eval runs

Before shipping a prompt change or a new agent version, run it against an eval rubric. Grade personality drift, factual accuracy, and tool-call correctness.

// Kick off a simulation + grading run, return immediately.
const ref = await client.agents.runEvalAsync("agent-id", {
templateId: "template_lead_qualification_v3",
simulationConfig: { turnsPerScenario: 6 },
});

// Poll the run record once the eval finishes (or stream live via streamEvents).
const result = await client.evalRuns.get(ref.runId);
console.log(result.scoreOverall, result.scoresByCategory);

See Evaluation for building rubrics and simulation users.