Overview
AI — Overview
The AI assistant is a tool-using CRM copilot. A user chats in natural language and the assistant reads and edits their workspace — query records, add a field, create a record, browse a smart catalog, look up emails or WhatsApp chats — by calling the same services the rest of the app uses, behind an authorization guard. It runs on four swappable LLM providers and answers over REST or a streaming WebSocket.
When should I use the AI assistant?
- You want an in-app chat that answers questions about the workspace ("how many open deals?", "who owns this contact?").
- You want the user to make changes by asking ("add a budget field to Deals", "mark this deal won") — with an explicit confirm before anything is written.
- You want the assistant reachable from web, mobile, or WhatsApp, on the same engine.
If you only need a one-off text generation (no CRM tools, no conversation), call the provider layer directly rather than the chat.
Key concepts
| Concept | What it is |
|---|---|
| Provider | A swappable LLM backend (OpenAI, Anthropic, Gemini, Kimi) behind AiProviderFactory — failover, caching, rate-limit, and credit metering live here. Agents never see a raw provider. |
| Agent | A named bundle of a system prompt + a tool whitelist + config. A supervisor routes each turn to a specialist agent (e.g. units, workspace_builder), which can hand off to another. |
| Tool | An auto-discovered @AiToolDef unit of work the model can call — ~50 across CRM, email, messaging, tasks, social, and analytics. The mode/agent decides which are exposed. |
| Confirmation gate | A write tool pauses for explicit user approval before it runs (human-in-the-loop). Enforced server-side, not just in the UI. |
| Channel | How the assistant is reached: REST + WebSocket (the in-app chat) or WhatsApp (server-side ingestion, replies via WAHA). |
A turn flows: user message → mode/agent picks tools → model calls a tool → the tool runs against a module service (RLS-pinned) → the model answers. Writes stop at the confirmation gate until the user approves. See Architecture.
Providers
The factory registers only providers whose API key is set; requests try the default
first, then fail over to the others. Pick the default with AI_DEFAULT_PROVIDER
(default openai); override any model with <PROVIDER>_DEFAULT_MODEL.
| Provider | AiProviderType | Default model | API key env |
|---|---|---|---|
| OpenAI | openai | gpt-4o | OPENAI_API_KEY |
| Anthropic (Claude) | anthropic | claude-sonnet-4-5-20250929 | ANTHROPIC_API_KEY |
| Gemini | gemini | gemini-2.5-flash | GEMINI_API_KEY |
| Kimi (Moonshot) | kimi | kimi-k2.5 | KIMI_API_KEY |
The assistant is v2
These docs describe the v2 multi-agent assistant (LangGraph.js) — the current direction of the product. A supervisor routes each turn to a specialist agent that runs the CRM tools. Surfaces (admin JWT):
- REST
/api/v1/ai-v2— blocking turns, addressed by conversation slug. - WebSocket
/ai-v2/chat— streaming tokens, tool progress, agent hand-offs, and the confirmation gate.
v2 is gated by AI_V2_ENABLED; when it's off the surface returns 404. (An older v1
engine — /ai-assistant, namespace /ai/assistant — still exists behind the scenes
and is being retired; this feature documents v2.)
Next
- The design → Architecture
- Build the chat UI → Frontend Integration
- Wire the backend → Backend Integration
- The endpoints → REST API