Chat Agent

Audience: Sales · Management · QA · Support · Engineering · Where in app: Settings → AI Agents → Chat Agent (tabs: AI Engine, Behavior, Chat Interface, Routing) · 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_human mode 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.

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 6, 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

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 / ai_to_human / human (see table above).
Takeover triggers	ai_chat	Phrases / turn-count thresholds that trigger handoff to a human.

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 emits connect-to-agent and 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, FactExtractionService extracts semantic facts from the transcript → persisted on PersonProfile.extracted_facts[] and agent_memories. State tracked on chats.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. See ms-ai/API_ENDPOINTS.md.
• RAG: company/company.service.ts — questionEmbeddings() (embed) → getUserContext() (top-20 by embeddings <=> $vector, then CohereService.rerankItems(... , 6)). Embeddings stored in the embeddings pgvector table keyed by company.
• Model wiring: constants.ts (CHAT_MODEL, EMBEDDINGS_MODEL) and cost-tracking/agent-model-bindings.ts (agent label chat).
• Facts: fact-extraction/ (FactExtractionService), factExtractionQueue (BullMQ).
• Cost: cost-tracking/ writes a usage_event / usage_charge per 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