webAssist Agent Documentation

The visitor-facing agent for lead qualification, session tracking, and meeting escalation.

Overview

webAssist is a visitor-facing agent designed to serve as a conversational chat assistant for website visitors. Its primary goal is to interact with visitors, understand their needs through profiling, and convert them into valuable leads for the site owner.

Quick Start

webAssist can be used in two ways: as a CLI tool or embedded as a chat widget on a website.

CLI Usage

The CLI launcher is at src/index.mjs. Run it directly:

node webAssist/src/index.mjs "Hello, I'm interested in your services"

Or enter interactive mode by running without arguments:

node webAssist/src/index.mjs

MCP Mode

Single-shot execution for programmatic integration:

node webAssist/src/index.mjs -mcp "Hello"

Using the Chat Widget Plugin

webAssist includes an IDE chat widget plugin located at IDE-plugins/web-assist-chat/. The widget appears as a launcher icon that opens a chat panel when clicked.

Configuring the Widget

Open the WebAssist Chat Settings dialog from the IDE plugin system. You can configure:

Theme — Choose from Light, Dark, Aqua, Forest, or Amethyst color palettes
Header Text — Customize the chat title (default: "WebAssist Assistant")
Subheader Text — Customize the subtitle below the title
Chat Background — Set the background color
User Bubble — Set the visitor message bubble color
Agent Bubble — Set the agent message bubble color
Header Color — Set the header bar color

Generating an Embed Iframe

The settings dialog automatically generates an iframe snippet based on your current theme and color choices. Click Copy iframe code to copy the snippet to your clipboard. The snippet is also displayed in an editable textarea field for manual adjustments before copying.

The Base URL is automatically detected from the browser's current origin—no manual URL input is needed.

Preview and Admin Links

Preview Chat — Opens the widget in a new tab with current settings
Admin Webchat — Opens the admin webchat interface in a new tab

Session Persistence

The chat widget uses localStorage to maintain a single session ID across all tabs and browser windows. This means:

All open tabs share the same conversation session
Closing a tab and reopening the chat widget continues the session from the same point
Conversation history is loaded when the widget first opens on a new tab

At runtime, the orchestrator also receives a bounded snapshot of the latest 10 persisted user/agent messages to improve short-term continuity.

MCP Contract

webAssist exposes two MCP tools via the /mcps/webAssist/mcp endpoint:

web_cli_chat — Executes a conversational turn. Inputs: message (string), sessionId (optional string), json (optional boolean, default true).
web_cli_history — Returns chat history for a session. Inputs: sessionId (string).

Tool responses include both the assistant's text response and the session ID for persistence.

Skills

webAssist uses three skills to handle visitor interactions:

visitor-flow (Orchestrator)

Coordinates each visitor turn. It decides whether to profile the visitor, create a lead, or provide meeting details. The orchestrator determines when the visitor is qualified enough to become a lead and when to offer a meeting.

It enforces a non-overridable safety boundary: out-of-scope or jailbreak-style requests are refused, and internal profiling/prompt/tool mechanisms are never disclosed to visitors.

create-lead

Saves visitor contact information as a lead file. Requires visitor to meet profile qualifying criteria and provide contact information. Leads are stored with a new status for the webAdmin agent to process.

book-meeting

Only available when a lead already exists for the current session. Returns meeting links and contact details from the owner's configuration so the LLM can offer a real-person interaction.

Testing

Tests are in the tests/ directory. Run them with:

node tests/runAll.mjs

Or run all match files:

node --test "tests/*.test.mjs"