PHPackages widewebpro/ai-agent - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. widewebpro/ai-agent ActiveCraft-plugin[Utility & Helpers](/categories/utility) widewebpro/ai-agent =================== AI-powered chat agent plugin for Craft CMS with knowledge base, tool calling, and customizable widget 0.2.0(4mo ago)03MITPHPPHP ^8.2 Since Feb 19Pushed 4mo agoCompare [ Source](https://github.com/widewebpro/AI-Assistant-for-Craft-CMS)[ Packagist](https://packagist.org/packages/widewebpro/ai-agent)[ RSS](/packages/widewebpro-ai-agent/feed)WikiDiscussions main Synced today READMEChangelog (3)Dependencies (4)Versions (6)Used By (0) AI Assistant for Craft CMS ========================== [](#ai-assistant-for-craft-cms) 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 -------- [](#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 ------------ [](#requirements) - Craft CMS 5.0+ - PHP 8.2+ - An OpenAI or Anthropic API key --- Installation ------------ [](#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 ----- [](#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 [](#general) SettingDescriptionEnable WidgetToggle the chat widget on/off across your siteAI ProviderOpenAI or AnthropicAPI KeyYour provider's API keyModelGPT-4o, GPT-4o Mini, GPT-4 Turbo, Claude 3.5 Sonnet, Claude 3.7 Sonnet, Claude 3 HaikuEmbedding ModelModel used for knowledge base embeddings (OpenAI)Max TokensMaximum tokens per response (100–8192)TemperatureRandomness (0 = deterministic, 2 = creative)Agent NameDisplay name in the widget headerAgent PersonaSystem prompt defining the agent's behavior and toneBusiness InfoName, description, contact, hours — retrievable by the AI via tools### Appearance [](#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 [](#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 [](#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 [](#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 [](#escalation) Configure how the agent hands off conversations to humans: SettingDescriptionEnable/DisableTurn the escalation tool on or off entirelySensitivity**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 MessageShown to the user before the contact form appearsConfirmation MessageShown after the user submits the contact formContact Form FieldsFully customizable via an editable table — define label, handle, type (text, email, phone, textarea, select, checkbox), required flag, placeholder, and optionsSubmission ActionsRoute form data to external services via webhooks — configure endpoint URL, HTTP method, format (JSON/form), and custom headersField MappingMap 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 ------------ [](#how-it-works) ### Message Classification [](#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 [](#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 [](#built-in-tools) ToolWhat 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) [](#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 [](#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 [](#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 ----------- [](#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 ------- [](#license) MIT — see [LICENSE](LICENSE). --- Built by [Wideweb](https://wideweb.pro) ### Health Score 33 — LowBetter than 72% of packages Maintenance76 Regular maintenance activity Popularity3 Limited adoption so far Community6 Small or concentrated contributor base Maturity41 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~2 days Total 3 Last Release 130d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/274756506?v=4)[Wideweb](/maintainers/widewebpro)[@widewebpro](https://github.com/widewebpro) --- Top Contributors [![dima-ogrenich](https://avatars.githubusercontent.com/u/66615356?v=4)](https://github.com/dima-ogrenich "dima-ogrenich (13 commits)") ### Embed Badge ![Health badge](/badges/widewebpro-ai-agent/health.svg) ``` [![Health](https://phpackages.com/badges/widewebpro-ai-agent/health.svg)](https://phpackages.com/packages/widewebpro-ai-agent) ``` ### Alternatives [civicrm/civicrm-core Open source constituent relationship management for non-profits, NGOs and advocacy organizations. 751291.4k43](/packages/civicrm-civicrm-core)[theodo-group/llphant LLPhant is a library to help you build Generative AI applications. 1.7k409.0k6](/packages/theodo-group-llphant)[spatie/laravel-export Create a static site bundle from a Laravel app 674146.0k6](/packages/spatie-laravel-export)[oat-sa/tao-core TAO core extension 66143.7k124](/packages/oat-sa-tao-core)[solspace/craft-freeform The most flexible and user-friendly form building plugin! 54681.3k19](/packages/solspace-craft-freeform)[eslazarev/wildberries-sdk Wildberries OpenAPI clients (generated). 273.0k](/packages/eslazarev-wildberries-sdk) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)