widewebpro/ai-agent

AI-powered chat agent plugin for Craft CMS with knowledge base, tool calling, and customizable widget

0.2.0 2026-02-23 16:16 UTC

Requires

• php: ^8.2
• craftcms/cms: ^5.0
• guzzlehttp/guzzle: ^7.0
• phpoffice/phpword: ^1.1
• smalot/pdfparser: ^2.0

MIT

README

A Craft CMS 5 plugin that adds an AI-powered chat widget to your website. Install it, configure from the admin panel — and you're live. No frontend code required.

Supports OpenAI and Anthropic as AI providers, with a built-in knowledge base (RAG), tool calling, streaming responses, and full customization from the control panel.

Features

• Embeddable chat widget — Auto-injected into your site's frontend. Shadow DOM isolated, zero dependencies, mobile responsive.
• Knowledge base (RAG) — Upload PDF, DOCX, TXT, or Markdown files. The plugin chunks, embeds, and searches them semantically.
• Smart message classification — Automatically detects greetings, questions, off-topic messages, and escalation requests. Greetings get a natural response; questions trigger tool-based retrieval; off-topic messages return a configurable fallback.
• Two-step AI pipeline — Step 1: message classification and tool selection. Step 2: context-aware answer generation based on tool results.
• 5 built-in tools — Knowledge base search, page context extraction, business info retrieval, topic listing, human escalation.
• Configurable escalation — When the agent can't help or the user asks for a human, a contact form appears in the chat. Fully customizable form fields (text, email, phone, textarea, select, checkbox), sensitivity level, and confirmation messages.
• Streaming responses — Real-time Server-Sent Events (SSE) streaming to the chat widget.
• Multi-provider — OpenAI (GPT-4o, GPT-4o Mini, GPT-4 Turbo) and Anthropic (Claude 3.5 Sonnet, Claude 3.7 Sonnet, Claude 3 Haiku).
• Full admin control — Every setting configurable from the Craft CMS control panel.
• Page targeting — Show or hide the widget on specific pages using glob URL patterns.
• Topic restrictions — Define allowed/disallowed topics with custom fallback messages.
• Conversation history — Browse and review all conversations from the admin panel. Escalated conversations are flagged with contact details.
• Agent avatar — Upload an image or provide a URL. Shown in the chat header and next to every assistant message.
• Webhook / CRM integration — Route escalation form submissions to any external service. Configurable endpoints, HTTP methods, headers, and field mapping with dot-notation support for nested payloads.
• Native Craft CP patterns — Settings pages use Craft's native full-page form, header tabs, Cmd+S save shortcut, unsaved-changes warnings, and breadcrumbs.
• Customizable appearance — Colors, fonts, position, welcome message, avatar, custom CSS/JS injection with live preview.
• Rate limiting — Per-minute message limits and max messages per conversation.

Requirements

• Craft CMS 5.0+
• PHP 8.2+
• An OpenAI or Anthropic API key

Installation

composer require widewebpro/ai-agent

Then install from the Craft control panel under Settings → Plugins, or run:

php craft plugin/install ai-agent

Setup

After installation, the plugin appears in the control panel sidebar. Click it to access the Dashboard, Conversations, and Settings.

All configuration is done under Settings, which contains six tabs:

General

Setting	Description
Enable Widget	Toggle the chat widget on/off across your site
AI Provider	OpenAI or Anthropic
API Key	Your provider's API key
Model	GPT-4o, GPT-4o Mini, GPT-4 Turbo, Claude 3.5 Sonnet, Claude 3.7 Sonnet, Claude 3 Haiku
Embedding Model	Model used for knowledge base embeddings (OpenAI)
Max Tokens	Maximum tokens per response (100–8192)
Temperature	Randomness (0 = deterministic, 2 = creative)
Agent Name	Display name in the widget header
Agent Persona	System prompt defining the agent's behavior and tone
Business Info	Name, description, contact, hours — retrievable by the AI via tools

Appearance

Customize the widget look and feel with a live preview:

• Avatar — Upload an image or paste a URL. Displayed in the chat header and as a small icon next to every assistant message. Falls back to initials if not set.
• Colors — Primary, secondary, background, text
• Position — Bottom-right or bottom-left
• Font — System default, Inter, Georgia, Mono
• Welcome message and placeholder text
• Custom CSS — Injected into the widget's Shadow DOM for full control
• Custom JavaScript — Runs after widget initialization

Knowledge Base

Upload documents to build your AI's information sources:

• Drag & drop or browse — supports PDF, DOCX, TXT, Markdown (max 10MB per file)
• Files are automatically parsed, chunked, and embedded for semantic search
• Reprocess or delete files at any time

The AI agent does not inject entire files into prompts. It performs semantic search and retrieves only the most relevant chunks per question.

Pages

Control where the widget appears using URL glob patterns:

• Add include or exclude rules (e.g. /products/*, /blog/**, /contact)
• No rules = widget appears on all pages

Restrictions

Control the agent's behavior boundaries:

• Allowed topics — If set, the agent only discusses these (one per line)
• Disallowed topics — The agent refuses these (one per line)
• Fallback messages — Custom responses for off-topic and error scenarios
• Rate limiting — Max messages per minute and per conversation

Escalation

Configure how the agent hands off conversations to humans:

Setting	Description
Enable/Disable	Turn the escalation tool on or off entirely
Sensitivity	Low — only when user explicitly demands a human. Medium (default) — when user clearly asks for help. High — also when user seems frustrated or agent fails repeatedly.
Escalation Message	Shown to the user before the contact form appears
Confirmation Message	Shown after the user submits the contact form
Contact Form Fields	Fully customizable via an editable table — define label, handle, type (text, email, phone, textarea, select, checkbox), required flag, placeholder, and options
Submission Actions	Route form data to external services via webhooks — configure endpoint URL, HTTP method, format (JSON/form), and custom headers
Field Mapping	Map form field handles to external field names. Supports dot notation for nested payloads (e.g. email → properties.email)

When escalation triggers, the chat widget displays an inline contact form built from your field definitions. Submitted data is saved to the conversation metadata, visible in the admin panel, and optionally forwarded to configured webhook endpoints.

How It Works

Message Classification

Every incoming message is classified into one of four categories:

1. Greeting — "hello", "hi", "thanks" → friendly conversational response, no tools called
2. Question — anything that needs information → tools are called to gather context
3. Off-topic — restricted or disallowed subject → returns the configured fallback message
4. Escalation request — user asks for a human → triggers the escalation flow (sensitivity-dependent)

Two-Step AI Pipeline

For questions (category 2):

1. Tool Selection — The AI decides which tools to call (search knowledge base, get page context, etc.) without answering directly.
2. Answer Generation — Tool results are injected as context. The AI generates a grounded answer based on retrieved data.

This prevents hallucination by ensuring the agent always retrieves information before responding.

Built-in Tools

Tool	What it does
search_knowledge_base	Semantic search across uploaded files
get_page_context	Extracts content from the page the user is currently on
get_business_info	Returns business information from settings
list_knowledge_topics	Lists available knowledge base files
escalate	Marks the conversation for human review and shows a contact form

Knowledge Base (RAG)

1. Files are uploaded and text is extracted (PDF, DOCX, TXT, MD)
2. Text is split into overlapping chunks
3. Each chunk is embedded via OpenAI's embedding API
4. At query time, the question is embedded and matched via cosine similarity
5. If no embedding match, MySQL FULLTEXT search is used as fallback

Escalation Flow

1. User asks to speak with a human (sensitivity determines threshold)
2. AI calls the escalate tool
3. Conversation status is set to escalated in the database
4. Chat widget shows an inline contact form built from the admin-defined fields
5. User submits their details → saved to conversation metadata
6. Enabled webhook actions fire — form data is mapped and sent to configured endpoints (CRMs, helpdesks, Zapier, etc.)
7. Confirmation message displayed
8. Admin can view escalated conversations, contact details, and webhook results in the CP

Chat Widget

• Shadow DOM for complete CSS isolation from your site
• Vanilla JS — zero frontend dependencies
• SSE streaming — responses appear in real-time
• localStorage — conversation history persists across page loads
• Mobile responsive with minimize/expand toggle

Admin Panel

Dashboard — Quick stats: total conversations, messages, escalated conversations, knowledge base files, and recent activity.

Conversations — Full history of all user conversations. Filter by status (active, escalated). Click into any conversation to read the complete thread and view escalation contact details.

License

MIT — see LICENSE.

Built by Wideweb