Download the PHP package shibuj/laravel-ai-chat-assistant without Composer

Laravel AI Chat Assistant

A BotMan-powered, tool-calling AI chat widget for Laravel. Drop in a floating chat widget backed by an LLM that can call your app's own PHP methods ("tools") to answer questions from real data — orders, stock, customers, whatever you define.

• 🔌 Swappable AI driver — ships with Gemini (Flash) support; add OpenAI, Anthropic, or anything else by implementing one interface.
• 🧰 Tool-calling — define what the assistant can look up as small, typed PHP classes. The model only ever answers from what your tools return.
• 👥 Multiple assistants — register one assistant for a single-role app, or several (customer / staff / admin, etc.) with your own logic deciding which one answers.
• 🎨 Ready-made widget — a themeable floating chat button + panel, publishable and fully customizable.
• ⚡ Artisan generators — make:ai-assistant and make:ai-tool scaffold new classes in seconds.

Requirements

• PHP 8.1+
• Laravel 10, 11, or 12
• A Gemini API key (or credentials for whichever driver you use)
• A CSRF meta tag and Font Awesome loaded on any page using the widget — see the two notes in Installation below

Installation

Publish the config file:

Publish the widget's CSS/JS assets:

Optionally publish the Blade view if you want to customize the widget markup itself:

Add your API key to .env:

Two things the widget expects from your layout

The widget's JS posts to the chat endpoint with fetch(), and its icons use Font Awesome — neither is bundled by the package, since both are things a Laravel app almost always already has. Add both to the <head> of any layout that includes the widget:

• CSRF meta tag — the chat route runs behind Laravel's web middleware group (CSRF protection included, by design — see Security). The widget's JS reads <meta name="csrf-token"> and sends it as X-CSRF-TOKEN on every request. Without this tag present, every message fails with "CSRF token mismatch" and the widget shows "The assistant could not answer. Check your connection and try again." Most full app layouts already include this tag (Laravel's default resources/views/layouts/app.blade.php does) — a bare welcome.blade.php or a minimal test page usually doesn't, so add it explicitly if you're testing on one.
• Font Awesome — the launcher and chat icons (fas fa-comments, fas fa-times, quick-action chip icons, etc.) use Font Awesome classes. If your app doesn't already load Font Awesome (via CDN or npm), the icons will render as empty boxes or nothing at all — the widget still works, it just looks broken. The CDN link above is the fastest fix; swap in your own npm-bundled version if you prefer not to depend on a CDN.

That's it — the package auto-registers its service provider and a chat route.

Quick start (single assistant)

1. Generate a tool

A tool is one thing the assistant can look up. Start small.

This creates app/AiTools/GetOrderStatusTool.php:

Important: never trust arguments the model sends for identity — always scope queries using the logged-in user, not anything the model could pass in. See Security below.

2. Generate an assistant

This creates app/Assistants/OrderAssistant.php:

3. Register the assistant

In app/Providers/AppServiceProvider.php:

With only one assistant registered, you don't need a resolver — it's used automatically.

4. Add the widget to your layout

In your main Blade layout — make sure the <meta name="csrf-token"> tag and Font Awesome link from Installation are in the <head> first — then just before </body>:

Done. Visit any page with that layout and you'll see the chat launcher.

Widget options

Icons use Font Awesome classes (fa-search, fa-history, etc.) — make sure Font Awesome is loaded on the page (see Installation), or swap the markup in the published view for your own icon set.

Multiple assistants

If your app has more than one kind of user who should get a different assistant (customer-facing vs. staff-facing vs. admin, for example), register several and tell the manager how to pick one:

Then in each layout, @include the widget with whatever copy/chips/scope fit that audience — the manager figures out which registered assistant actually answers based on the resolver, independent of what the widget's name/welcome text says.

Restricting a tool per role

If one assistant should expose different tools to different users of the same role (e.g. staff members with different permissions), gate it inside the assistant, not the tool:

hasAccess() is checked before every message; if it returns false, noAccessMessage() is sent instead and no tool ever runs.

Swapping the AI driver

The package ships two drivers — gemini (default) and a minimal openai example. Swap globally:

Or pin one specific assistant to a different driver, regardless of the global default:

Writing your own driver

Implement ShibuJ\AiChatAssistant\Contracts\AiDriver:

Register it in config/ai-assistant.php:

Then set AI_ASSISTANT_DRIVER=anthropic or use driverName() on a specific assistant.

Security

The package deliberately keeps identity out of tool arguments. A few rules worth following in every tool and assistant you write:

• Never let the model tell you who the user is. Scope every query using the authenticated user (auth()->id(), session(), etc.) inside your Assistant or Tool constructor — never from $args passed by the model.
• Return only what the model needs. Don't dump entire Eloquent models into a tool result; map to a plain array with just the safe fields.
• Never return credentials, secrets, or payment details from a tool, even if your app has them available. If a tool wraps sensitive configuration, build an explicit allowlist rather than passing a raw config object through.
• Keep the assistant read-only unless you explicitly design a write action. Any tool that changes data should be a deliberate, narrow exception — the shipped example tool and stub are both read-only by design.
• End every system prompt with an instruction to ignore embedded instructions — the stub does this for you; keep that line when you customize the prompt.
• CSRF protection stays on. The chat route runs through Laravel's web middleware group intentionally, so cross-site requests can't hit your assistant's tools. Add the CSRF meta tag (see Installation) rather than removing the route from CSRF protection.

How conversation history works

Each scope you pass to the widget gets its own conversation, cached server-side (default: file cache store, last 6 turns, 30-minute TTL — all configurable in config/ai-assistant.php). The widget also mirrors the visible chat log in the browser's sessionStorage so a page navigation doesn't visually clear the chat, but a full page reload starts fresh on both ends.

Interactive actions (buttons)

If a tool needs the user to confirm something before it happens (e.g. "place this order?"), set pendingAction on the assistant from within your reply() flow — typically by having a tool set a property your Assistant subclass checks after driver->converse() returns. The simplest approach: store draft state yourself (cache, DB) and check for it after calling the driver in an overridden reply():

The bundled AssistantChatController will render these as buttons automatically. Handling __confirm__:... / __cancel__:... button presses is app-specific — extend or replace the controller's fallback/hears wiring for that (see Customizing the controller below).

Customizing the controller

If you need extra BotMan hears() handlers (e.g. for confirm/cancel buttons, as above), publish nothing — instead, register your own route pointing at your own controller that composes the package's pieces:

Then point the widget's data-endpoint at your own route instead of the package's, either by publishing the view (--tag=ai-assistant-views) and editing it, or by setting 'route' => ['path' => '/my-assistant-chat'] in the published config and building your own controller at that path.

Testing your tools

Tools are plain classes — test them directly, no HTTP or AI calls needed:

Configuration reference

Troubleshooting

"CSRF token mismatch" / widget always shows "The assistant could not answer"

The page including the widget is missing the CSRF meta tag. Add this to the <head>:

The widget's JS reads this tag and sends it as the X-CSRF-TOKEN header on every request; without it, Laravel's VerifyCsrfToken middleware rejects every message with a 419 response, which the widget surfaces as a generic connection error. This is easy to miss on a bare test page (e.g. the default welcome.blade.php) since a full app layout usually already has this tag from Laravel's default scaffolding.

Chat icons show as empty boxes or don't appear at all

Font Awesome isn't loaded on the page. Add a CDN link (or your own npm-bundled copy) to the <head>:

The widget's launcher, close/new-chat buttons, and quick-action chips all use fas fa-* classes. The widget still functions correctly without Font Awesome present — only the icons are affected.

vendor:publish --tag=ai-assistant-assets fails with "Can't locate path"

This means the installed package version is missing its resources/assets/ files (a packaging bug in early 0.1.x releases, fixed in v0.1.4+). Update to the latest version and republish:

Composer can't find the package / version conflict on install

Double check you're requiring the exact published name — composer require shibuj/laravel-ai-chat-assistant — and that your Laravel/PHP version falls within the package's declared require range in its own composer.json. Run with -vvv for the exact conflicting constraint if it still fails:

Upgrading

Check CHANGELOG.md before upgrading a major version — the Assistant and Tool contracts are considered the stable public API; changes to them will always be a major-version bump.