Sonar AI — User Manual

1. What Is Sonar AI

Sonar AI is an AI agent embedded directly in NetSuite as a Suitelet. It is not a separate integration or an external chatbot bolted onto NetSuite — it runs inside your account, as a page you navigate to like any other NetSuite screen, and every action it takes executes under your own NetSuite login, subject to your role's actual permissions. There is no service account, no elevated privilege, and no bypass of NetSuite's own security model.

How it's built

The architecture has three parts:

• A browser-side chat application (SPA) — everything you see and click. It holds your conversation, your settings, and (critically) your AI provider API key, all in your browser's localStorage. Nothing here is stored on NetSuite's servers.
• A Suitelet relay — the server-side NetSuite code that executes tool calls (SuiteQL queries, record loads, file operations, etc.) using NetSuite's native SuiteScript modules, under your session and your role.
• An AI model provider — Anthropic, OpenAI, xAI, Mistral, or the NetSuite-bundled Cohere integration. Your browser talks to the provider directly wherever possible; the Suitelet is not in the middle of that conversation except for Cohere, which is relayed through NetSuite's own N/llm module.

What makes it different from asking a generic AI chatbot about NetSuite

A generic chatbot can only guess at your account's schema, your customizations, and your data. Sonar actually queries your live account — it runs real SuiteQL against your real tables, loads your real records, and reads your real custom fields. When it doesn't know something (a field id, a script's behavior, a saved search's filters) the house rule is to look it up rather than guess, because a wrong-but-plausible field id is the single most common way an AI agent silently gets something wrong in NetSuite.

2. First Launch

Terms of Use

The first time you open Sonar AI (or after a Terms of Use version bump), you'll see an acceptance screen. It explains, in plain terms, that Sonar uses third-party LLM APIs (Anthropic, OpenAI, Google, Mistral, xAI, Cohere, or any OpenAI-compatible provider you configure) to plan and execute actions, that those actions can create/modify/delete records based on the model's reasoning, and that you are responsible for reviewing destructive operations before approving them and for choosing which provider receives your data. Acceptance is recorded in your browser's localStorage.

License / subscription check

Sonar checks a subscription/license status on load, cached for about 12 hours so it doesn't re-check on every page view. If your subscription needs attention, a modal offers a Refresh action.

Choosing a provider and model

Sonar needs an AI model to run. On first use, open Settings (gear icon) and either:

• Enter an API key for Anthropic, OpenAI, xAI, or Mistral (each provider needs its own key, entered once), or
• Switch to Cohere (/cohere), which needs no key at all — it rides your NetSuite account's own bundled LLM allowance via N/llm. Cohere is text-only (no native tool-calling) and is best thought of as a no-setup fallback, not the primary way to drive Sonar.

Theme

Sonar defaults to your OS-level light/dark preference; a toggle in the header switches it manually.

3. The Chat Interface

Composing messages

• Enter sends your message; Shift+Enter inserts a newline.
• You can attach files directly to a message (CSV, JSON, code, images). Large files upload in chunks automatically — you don't need to do anything differently for a big file versus a small one.
• A Stop button appears while Sonar is working, letting you abort a turn mid-stream (useful if you realize you asked the wrong question, or a tool call is taking too long).

What you see per turn

• Tool call cards — each tool Sonar calls renders as an expandable card with a short, human-readable purpose line at the top, so you can skim a long conversation without opening every card.
• Usage chip — on each assistant response (Anthropic-provider only; Cohere shows a "NS-bundled, no per-token charge" note instead) a small chip reports tokens in/out and estimated cost for that turn. Click it for a detailed breakdown, including savings from prompt caching.
• Rate-limit countdown — if your provider returns a 429, Sonar shows a visible countdown rather than failing silently or retrying invisibly.
• Toasts — brief confirmations/errors in the corner (e.g. "Model: claude-opus-5", "Set your API key in Settings").

Managing conversations

• Conversations persist in your browser's localStorage across page reloads.
• /clear starts a fresh conversation.
• /export downloads the current conversation as Markdown, including tool results and per-message cost lines — useful for sharing a session or comparing model performance across runs.
• Very long conversations are auto-compacted: once you approach ~75% of the active model's context window, older messages are summarized into a single block (goals, decisions, tool findings, account context preserved) via a paid LLM call charged to your session. See §20 for what this means for accuracy.

4. Asking Questions About Your Data

Sonar has several distinct ways to answer a data question, and it's worth knowing which one it reaches for:

SuiteQL (runSql)

Direct, Oracle-flavored SQL against NetSuite's query engine. This is the workhorse for custom slicing, joins across tables, and anything a saved search or standard report can't express. Results over ~10KB are paginated/truncated automatically with a clear marker; Sonar refines the query rather than guessing when that happens.

Standard NetSuite reports

When you ask for something that has an actual NetSuite report — an Income Statement, Balance Sheet, A/R Aging, Comparative Income Statement, and so on — Sonar uses the real, NS-rendered report rather than reconstructing the numbers itself in SQL. The flow is: reportsList (find the report) → reportInfo (discover its exact filter fields and valid values) → reportRun (execute it, with named period presets like Q1TFY or custom date ranges).

Saved searches

savedSearchList finds a search by name, savedSearchInspect (advanced tool group) shows its filters/columns without running it, and savedSearchRun executes it — optionally with filter/column overrides.

Record inspection

recordJson / recordXml load a record's full state (all fields, all sublists). recordTypeDescribe answers "what fields does this record type even have" by loading a live sample. fieldDescribe drills into one field — its type, whether it's really mandatory, and (for select fields) its valid options, resolved live from the account rather than guessed.

5. Getting Files Out

Two distinct mechanisms, and Sonar defaults to the one that leaves less clutter:

Artifacts (the default)

artifactCreate produces an ephemeral, downloadable file held as a browser Blob — it appears as a clickable chip on the tool call and in a footer Artifacts panel, but is never written to the NetSuite File Cabinet. It lives only for the current browser session. This is the default for "give me this as a download" requests (CSV exports, generated reports, JSON dumps).

Bulk SQL exports: sqlToArtifact

When you want raw query results (potentially thousands of rows) dumped straight to a file, sqlToArtifact runs the query and formats the file entirely server-side — the rows never pass through the AI model as tokens. This is dramatically faster than the alternative (query, then re-emit every row as model output) for anything beyond a trivial row count, and it's what Sonar reaches for whenever a bulk data dump is requested.

File Cabinet writes (when it should persist)

fileCreate writes a real, persistent file into NetSuite's File Cabinet. Sonar reaches for this only when the file genuinely needs to live in NetSuite — Suitelet source being deployed, integration assets, reference documents meant to outlive the browser session (like this manual).

6. Making Changes Safely

The dry-run → diff → approval workflow

recordCreate, recordUpdate, recordSubmitFields, recordDelete, and their bulk equivalents all accept dryRun: true. A dry run computes and returns exactly what would change (a before→after field diff, or a delete summary) without saving anything. For any update you haven't spelled out field-by-field yourself, Sonar dry-runs first, shows you the diff as a table, and only proceeds after you approve — the diff shown to you always comes from the dry-run result itself, never from Sonar's own description of what it intends to do.

The approval-gate modal

Destructive or modifying tool calls surface an approval modal before executing, with an "always allow" option for that specific tool if you want to stop being asked for routine, low-risk operations within a session.

What Sonar will never do

• Create script or scriptdeployment records. This is a hard, deliberate security boundary — not a permissions gap you can unlock by adjusting a role. Deploying a new script is always a human-executed step: Sonar uploads the source file and walks you through Customization > Scripting > Scripts > New, with exact field values.
• Delete production records without your explicit confirmation — see §9.
• Silently fall back to a different approach when the requested one fails (e.g., SQL instead of a standard report) without asking first.

7. Tool Groups

To keep Sonar's default toolset small and easy to reason about, most core capabilities (SuiteQL, reports, record CRUD, files, artifacts, search, web fetch, skills) are always available. More specialized capabilities are organized into deferred tool groups that Sonar loads on demand with toolGroupLoad as soon as a task points to them — you'll typically never notice this happening except as a brief "N tools now callable" note.

8. The Permission Mask

Sonar runs in one of three modes, controlled by a shield icon in the header:

Widening the mode (e.g., Read-only → Standard) shows a confirmation before taking effect.

9. Production Delete Confirmation

On top of the permission mask, real deletes (recordDelete, recordDeleteBulk, fileDelete) in a production account require an additional flag, confirmedByUser: true, or they are rejected with CONFIRMATION_REQUIRED. The intended workflow is always: dry-run → show you exactly what would be deleted → get your explicit approval of that specific delete → only then re-issue with the flag set.

Practical implication: always read the dry-run diff Sonar shows you before saying yes to a delete. Your "yes" is the actual control here.

10. The Audit Trail

Every mutating tool call — success, error, dry-run, or blocked — is logged automatically to NetSuite's script execution log with the title prefix SONAR_AUDIT. This logging happens in the dispatch layer, not by the AI model choosing to log something, so it can't be skipped or talked around.

What's recorded

Each entry's detail field is JSON:

{ ts, user: { id, name, role }, tool, outcome, errorCode, mask, purpose, target, args }

outcome is one of success / error / dryrun / blocked. args is clipped (~3.5KB) rather than storing arbitrarily large payloads.

How to look it up

The built-in Sonar Activity viewer shows the last 100 entries. For anything deeper, query directly:

SELECT date, title, detail FROM scriptnote
WHERE title LIKE 'SONAR_AUDIT%'
ORDER BY date DESC

11. Privacy Mode

Privacy Mode lets you run analyses on customers, vendors, employees, and contacts without their identities ever entering the AI model's context — useful for clustering, segmentation, or any workflow where the underlying pattern matters more than the names attached to it.

The strictness dial

A header toggle (👤) cycles through three states:

How it works

• Column-manifest projection — the primary mechanism. Query results are projected against a default-deny manifest: an undeclared string column is withheld rather than assumed safe.
• Dictionary redaction (backstop) — a browser-only lookup swaps real names for stable tokens derived from internal id: CUST-<id>, VEND-<id>, EMP-<id>, CONT-<id>. Tokens are stable across a session (and across dictionary rebuilds) — the same customer always gets the same token, so patterns across multiple questions stay analyzable.
• Entity-specific tool blocklist — tools whose whole purpose is looking up an identity by name (customerSearch, pageFetch, webFetchBrowser, direct entity recordLoad/recordJson) are blocked while Privacy Mode is on.

A tightening-only privacySpecApply tool lets you describe additional protections in plain language (extra never-grant columns, extra sensitive terms, extra blocked tools) which get applied with your confirmation. A synthetic canary customer exists in this account specifically to self-test the redaction pipeline end-to-end.

Privacy Mode and a private/self-hosted AI provider are complementary, not competing, protections: Privacy Mode keeps entity identities out of whatever model you're using; choosing where that model runs (see §17) determines whether your data leaves your organization's network at all.

12. Skills & Field Notes

Skills

Skills are curated reference documents Sonar loads before doing something that needs deep, NS-specific knowledge — SuiteQL quirks, SuiteScript hard limits, roles and permissions, and account-specific conventions. There are two kinds:

• Bundled skills — ship with Sonar itself (e.g. SuiteQL essentials, SuiteScript essentials).
• Custom skills — markdown files you (or Sonar, on your instruction) author in the /SuiteScripts/sonar-skills File Cabinet folder. These carry house rules and account-specific conventions that override generic approaches within their subject area. Changes take effect immediately — no redeploy.

skillList shows what's available; skillRead loads one before relevant work begins.

Field notes

Field notes are Sonar's persistent memory of this specific account: verified facts, configuration, schema quirks, and known-good query patterns discovered in past sessions. They live in a single markdown file (sonar-field-notes.md, injected at load) and are treated as hints, never authority — if live introspection ever contradicts a field note, the live account wins, and Sonar flags the stale note for correction. You can ask Sonar to "update your field notes" after a session to distill what was genuinely learned (verified ids, corrected mistakes, stated preferences) into surgical edits, keeping the file under a size ceiling and never recording anything sensitive.

13. Processes

Processes are supervised, multi-step workflows defined as markdown files in /SuiteScripts/sonar-processes — things like a customer onboarding check, month-end close, or a permissions audit. Each defines an ordered sequence of steps tagged research / action / gate.

Running one

Say "run <process name>" and Sonar loads the definition, renders a live checklist card, and executes step by step — marking each step running/done/error as it actually happens (never marking a step done that wasn't executed). A gate step always stops and asks you directly in the conversation; gates are never relaxed by a process run, and every mutation inside a process still goes through the normal dry-run + approval flow from §6.

The starter library

processStarterSeed installs a bundled library of account-agnostic process definitions into sonar-processes, without ever overwriting an existing file of the same name — your edits and deletions always win. It always previews a dry-run plan (CREATE vs. SKIP per file) for your approval before writing anything.

Authoring or importing your own

If you want to write a new process, or someone hands you a process definition file, Sonar loads a dedicated authoring guide skill first — it covers the file anatomy, the quality bar, and (for imported files specifically) an intake protocol: validate, check for collisions with existing processes, run a quality review, then trial-run it ad hoc before installing it for real.

14. Subagents

For a self-contained, read-only investigation that would otherwise burn many tool calls whose intermediate results you don't need to see — surveying an unfamiliar schema, searching through a large source file, archaeology on old customizations — Sonar can dispatch a subagent: a nested agent loop with its own private context and a restricted, read-only tool whitelist.

• subagentRun — one investigation. You watch its live activity in a tool card; only its final summary re-enters the main conversation.
• subagentRunParallel — 2–3 independent investigations dispatched concurrently under one approval, taking the wall-clock time of the slowest rather than the sum of all three. Used, for example, when researching several unrelated AI providers' documentation at once.

15. Second Opinion

Second Opinion requests an independent, adversarial review of Sonar's own analysis from a different Anthropic model — a structural check against a single AI's blind spots, using an API key you supply and control separately from your main provider key.

Setup

Settings > Second Opinion — enter a dedicated Anthropic API key (a workspace key with its own monthly spend cap is recommended), and optionally set a per-session spend ceiling and an auto-approve threshold below which review dispatches don't need individual confirmation.

How a review packet is built

Sonar assembles source data first (raw extracts, not its own prose), then computed metrics with the formulas that produced them so arithmetic is independently checkable, then claims stated neutrally with stable ids — withholding its own recommendations on the first pass so the reviewer isn't anchored by them.

Guardrails

• Key custody: resolved in your browser only, never a tool parameter, never entering the model's context.
• Spend ceiling enforced per session; a confirmation with estimated cost shows before a dispatch that exceeds your auto-approve threshold.
• Rate limit: 3 dispatches per minute.
• Provenance: every result includes a provenance line disclosing the reviewing model, which must always be surfaced when you see or share the review.
• If no key is configured, Sonar relays the setup steps and stops — there's no in-chat workaround by design.

16. Projects & Prompt Library

Projects

A Project is a named, importable markdown document (similar in spirit to a CLAUDE.md file) that provides standing context for a conversation — house rules, background on an initiative, terminology specific to how your organization talks about its own data. One Project is active at a time, managed via a header button and modal.

Prompt Library

A modal offering a hosted library of ready-made prompts, relayed from an external service (suitestep.com) via a signed request.

17. Settings Reference

18. Slash Command Reference

19. Complete Tool Catalog

Sonar has roughly 70–80 distinct tools. The core set below is always callable; the grouped sets require toolGroupLoad first (see §7). This catalog is organized by function, not alphabetically, so related tools sit together.

Always available — data & reporting

Always available — records

Always available — search & lookup

Always available — files & artifacts

Always available — web & compute

Always available — orchestration & meta

Deferred group: customize

Deferred group: roles

Deferred group: scripting

Deferred group: bulk

Deferred group: transactions

Deferred group: comms

Deferred group: advanced

Verified live in this account on 2026-08-29 — this is the exact set toolGroupLoad("advanced") returns.

20. Troubleshooting & Limits

Common error codes

Governance & performance

• Governance units — each tool call draws from a per-request NetSuite governance budget. Bulk operations are capped at 100 records per call by design; large jobs are batched across multiple turns rather than attempted in one unbounded loop.
• TOON encoding — tabular tool results (SuiteQL rows, saved search results, etc.) are returned in a compact CSV-like format prefixed TOON[rows=N,cols=...] rather than verbose JSON, to keep large result sets affordable in the model's context.
• Truncation — any single result over roughly 10KB is clipped (head + tail) with a [... TRUNCATED N bytes ...] marker. When you see this, the right move is a tighter query or filter, not a blind retry.
• Conversation compaction — see §3. Once older messages are summarized, fine-grained detail from early in a long conversation may be lost even though the gist is preserved; for anything you'll need to reference precisely later, /export before it happens.

If something looks wrong

• Check agentHealth (version, active mask, governance remaining) as a first diagnostic.
• Check the audit trail (§10) for what actually executed, rather than relying on the conversation's own narrative of what happened.
• If a standard report run fails, Sonar will show you the actual NetSuite error rather than substituting a workaround — that's deliberate; ask for the specific fallback you want rather than expecting an automatic one.