Chat Agent
Audience: Sales · Management · QA · Support · Engineering · Where in app: Settings → AI Agents → Chat Agent (tabs: Behavior, Routing, Chat Interface, Pre-Chat Form, + Tags when GHL is connected, + Bot Flow when bot_flow_enabled) · Plan availability: All plans (model/usage limited by AI Credits — see AI Credits)
The Chat Agent is the AI that responds to visitor chat messages in the widget. When a visitor opens the chat and types, the Chat Agent answers in real time, grounded in the content you trained it with (your Knowledge Base) and, for verified visitors, what the platform already knows about that person. It works around the clock, even outside your working hours, and can hand off to a human when a conversation needs a personal touch.
What it does
- Answers visitor questions about your business, products, services, pricing, and policies.
- Pulls answers from your Knowledge Base (scraped website content, PDFs, manual FAQ Q&A) via RAG.
- Personalises responses for verified visitors using identity-graph context (name, CRM stage, past conversations, bookings, extracted facts).
- Greets visitors with a custom welcome message and guides them toward a next step (book a call, fill a form, talk to a human).
- Hands off to a human in
ai_to_humanmode when it can't resolve the conversation. - Extracts contact details (name/email/phone) and semantic facts from the conversation for the identity graph.
- Emits quality signals (sentiment, outcome, topics, "failed to answer" count) that Nox and analytics surface.
How it works
Routing modes — set on companies.ai_config.chat_routing:
| Value | Behaviour |
|---|---|
ai | The Chat Agent handles the conversation end-to-end. |
ai_to_human | The AI handles it until a takeover condition fires, then hands off to a human agent. |
human | No AI; goes straight to the human queue. |
The schema default is ai since 2026-10-08 (backend 772445905, ms-comm mirror d52002f; was ai_to_human) — existing companies keep their stored value. The Routing tab only offers ai (AI Only) and ai_to_human (AI to Human); human is legacy-only. ai_to_human reveals chat_queue + chat_queue_max_per_agent (FIFO human-chat queue, 0 = unlimited).
Model routing (multi-provider). ms-ai resolves the model from companies.ai_config.chat_model + chat_model_provider. The platform is multi-provider: Anthropic (claude-*), OpenAI (gpt-*), plus other providers configured in the catalog (e.g. Groq/Mistral). The service-wide default is the CHAT_MODEL env var (currently gpt-5.1; verify the live value per environment). The same CHAT_MODEL dial also powers the safety/guardrail filter and the Nox admin assistant — they share one model unless split in constants.ts (see cost-tracking/agent-model-bindings.ts).
RAG grounding. Before answering, ms-ai embeds the visitor's question (OpenAI text-embedding-3-small), runs a vector similarity search (cosine distance) over the company's embeddings pgvector table, fetches the top ~20 candidate chunks, then Cohere-reranks down to the top KB_TOP_RESULTS (default 4), and injects those as a "Knowledge" section in the system prompt. If nothing relevant is found the agent falls back to its persona prompt only (more generic, higher hallucination risk — keep the KB tight). See Knowledge Base and Knowledge-Base RAG.
Identity-graph context (verified visitors only). When the visitor has a verified PersonProfile, the prompt also includes: identity (name/email/phone/company/location), engagement (lead score, visit count, first/last seen), recent pages this session, past conversations (last 5 chat/call summaries), CRM state (HubSpot/GHL lifecycle stage, deals, tags), deduped bookings, and extracted facts (e.g. "budget under $5k"). Sections are toggleable globally by super-admin via IdentityGraphDefaultsModel.enabled_sections[]. For unverified ("claimed") sessions, only the current session is in context — no cross-session memory. See Identity Graph.
Streaming. POST /agents/v2/ask-question streams the answer token-by-token over SSE; POST /agents/ask-question is the non-streaming variant. Both are secret-auth (service-to-service, called by the backend, not the browser directly).
Configuration & options
Configured in Settings → AI Agents → Chat Agent. Stored on companies.ai_chat and companies.ai_config.
AI Engine tab (hidden)
The tab is commented out of ChatAgent/index.vue; the fields below are still read but not edited here.
| Setting | Field | What it does |
|---|---|---|
| Model selection | ai_config.chat_model + chat_model_provider | Which LLM powers the agent (speed/accuracy/cost trade-off). |
| Response style | ai_chat.response_size | concise / detailed — biases answer length. Plus creativity/precision controls. |
Behavior tab
| Setting | Field | What it does |
|---|---|---|
| Mode | ai_chat.setting | quick (template prompts driven by tone) or advanced (full prompt control). |
| Instructions | ai_chat.agent_instructions | The system prompt (advanced mode). The more specific, the better the responses. |
| Personality / Tone | ai_chat.tone | professional / friendly / casual / etc. — used in quick mode. |
| Agent name | ai_chat.agent_name | Name shown to the visitor. |
Chat Interface tab
| Setting | What it does |
|---|---|
| Widget appearance | Colors/layout of the chat window. |
| Greeting message | First message shown before the visitor types — sets the tone. |
Routing tab
| Setting | Field | What it does |
|---|---|---|
| Chat routing | ai_config.chat_routing | AI Only (ai, default) / AI to Human (ai_to_human). |
| Takeover triggers | ai_chat | Phrases / turn-count thresholds that trigger handoff to a human. |
Bot Flow tab
Shown only when company.bot_flow_enabled === true (super admin, per company or agency-wide). Hosts the Bot Flow Builder canvas full-width; ?tab=botflow opens it and the old /settings/ai/bot-flow route redirects here. See Bot Flow Builder.
Tags tab (PostChatTags.vue → ai_chat.post_chat_tags)
Shown whenever GHL is connected (go_high_level.access_token) — the super-admin widget_chat_tags_enabled gate was removed 2026-09-25 (f1d39fb38 / 021eae6b). One built-in outcome, Chatted with the visitor (engaged, editable tag name, blank → engaged), plus custom {description, tag} rules the AI matches against the transcript. ChatTranscriptEmailJob._applyChatTags applies them after the chat, replacing the feature's managed tag set on the contact (GhlPostCallTagsService.managedTags). Note this means every GHL-connected tenant's contacts now get the engaged tag after a real chat, with no opt-in.
QA/support tip: to confirm which model and prompt a tenant is running, ask Nox ("what model does the chat agent use?") or read companies.ai_config.chat_model and companies.ai_chat.agent_instructions.
Behaviors & edge cases
- Takeover (
ai_to_human). The AI hands off when: it explicitly flags the conversation as needing human help; the visitor types a configured trigger phrase; N turns pass without resolution; or the visitor asks for a human. On handoff the AI emitsconnect-to-agentand available agents are notified. - Hallucination guard. Answers are grounded in retrieved KB chunks; when retrieval returns nothing the agent leans on its persona prompt and is more likely to be generic/wrong. Keep the KB current; use focused FAQs for high-frequency questions.
- Fact extraction. After a chat ends,
FactExtractionServiceextracts semantic facts from the transcript → persisted onPersonProfile.extracted_facts[]andagent_memories. State tracked onchats.fact_extraction_state(pending/queued/complete/skipped). - Credit exhaustion. Each LLM turn deducts AI credits (logged with
source = chat_agent). When credits run out the chat falls back to a human queue (or shows an offline "we'll get back to you" message). Fact extraction is skipped (fact_extraction_state: skipped). See AI Credits. - No reply, no charge. If a visitor messages but the AI doesn't reply (e.g. instant handoff to a human), no credits are consumed for that interaction.
- Multi-persona. There is one Chat Agent per company. "Multiple personas" are achieved with per-page prompt overrides via page rules (same agent, different prompt) — an advanced feature.
Plan & limits
- Available on all plans; usage is bounded by AI Credits (each turn is priced per token, weighted by model). See AI Credits.
- Knowledge-base size (documents / total tokens / page caps) is plan-dependent — verify under billing/plans.
- Sales/management: heavier/more capable models consume more credits per turn; concise response style and a tight KB reduce burn.
Quality / KPIs
Tracked on chats.knox.* and surfaced to Nox/analytics:
| Field | Meaning |
|---|---|
sentiment | positive / neutral / negative |
outcome | booked / contact_captured / no_action / escalated |
topics_covered[] | fixed taxonomy of topics |
agent_failed_to_answer_count | times the AI gave up on a question (find KB gaps) |
questions_asked_by_visitor[] | surfaced in Nox queries |
Nox queries: "show me chats where the AI struggled this week" (agent_failed_to_answer_count > 0); AI-vs-human conversion comparison; whether an extracted fact appears across visitors (cohort signal). Tools: knox-call-transcripts, knox-extracted-facts, knox-aggregate(metric=conversation_quality_breakdown).
Technical implementation
- Service: ms-ai, module
agents/(KnockAgentsModule—agents.controller.ts,knock-agents.service.ts). - Endpoints:
POST /agents/ask-question(non-streaming),POST /agents/v2/ask-question(SSE streaming),POST /agents/auto-trigger-message,POST /agents/chat-summary-notification,POST /agents/extract-contact-details. Seems-ai/API_ENDPOINTS.md. - RAG:
company/company.service.ts—questionEmbeddings()(embed) →getUserContext()(top-20 byembeddings <=> $vector, thenCohereService.rerankItems(... , KB_TOP_RESULTS)). Embeddings stored in theembeddingspgvector table keyed by company. - Model wiring:
constants.ts(CHAT_MODEL,EMBEDDINGS_MODEL) andcost-tracking/agent-model-bindings.ts(agent labelchat). - Facts:
fact-extraction/(FactExtractionService),factExtractionQueue(BullMQ). - Cost:
cost-tracking/writes ausage_event/usage_chargeper call (input/output tokens). See AI Credits. - Identity: ms-ai pulls verified-visitor context via the identity-graph gRPC client. See Identity Graph and Nox Assistant.
Related
- Knowledge Base — what the agent reads.
- Call Agent — the voice equivalent.
- Chatbot Flow Builder — the rules-based alternative.
- AI Credits — what each turn costs.
- ms-ai service · Knowledge-Base RAG · Identity Graph