Laravel Chatbot

Conversation-persisted AI chat scaffolding for Laravel, built on top of the Laravel AI SDK. It gives you a ChatService you can call from a controller or job, and stores every conversation and message in your own database so history survives across requests.

Requirements

• PHP 8.3+
• Laravel 13.x
• laravel/ai installed and configured with at least one provider

Installation

composer require omarseyam/laravel-chatbot
php artisan chatbot:install
php artisan migrate

chatbot:install will:

• Publish config/agents.php
• Publish the agent_conversations and agent_conversation_messages migrations
• Copy the chat source files into app/Ai/... and the two models into app/Models/...

These files become part of your application once copied — feel free to edit them. Re-running the command won't overwrite anything that already exists unless you pass --force.

Configuration

Register your agents in config/agents.php by mapping an alias to an Agent class:

return [
    'assistant' => \App\Ai\Agents\AssistantAgent::class,
];

The alias is what you'll pass as agent on a ChatRequest.

Usage

use App\Ai\Data\ChatRequest;
use App\Ai\Services\ChatService;

$response = app(ChatService::class)->ask(new ChatRequest(
    prompt: 'What can you help me with?',
    conversationId: null, // pass an existing conversation id to continue it
    agent: 'assistant',
));

// $response = ['conversation_id' => '...', 'content' => [...]]

Conversations and messages are scoped to the authenticated user (Auth::id()), so a conversationId can only be resumed by the user who started it.

Models

• App\Models\AgentConversation — one row per conversation, with a messages() relation and a title generated from the first prompt.
• App\Models\AgentConversationMessage — one row per message, storing role, content, agent, usage, meta, attachments, tool_calls, and tool_results.

AgentConversation also defines a post() relation to a Post model via a conversation_id column, used to protect conversations that were turned into published content from being pruned. If your app doesn't have that concept, remove the post() relation and the whereDoesntHave('post') clause in prunable().

Pruning old conversations

AgentConversation uses Laravel's Prunable trait to clean up conversations older than an hour (excluding any tied to a Post, and cascading to their messages). Schedule it in routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('model:prune')->daily();

Contributing

Issues and pull requests are welcome at github.com/omarseyam/laravel-chatbot.

License

The MIT License (MIT). See LICENSE for details.