A Laravel starter kit for an LLM chat interface, built with Livewire, FluxUI, and the Laravel AI SDK.
The chat streams replies, renders markdown, calls tools, asks the user before a tool changes something, and stores every conversation. Apart from the Alpine component that renders streamed markdown, it is written in PHP and Blade.
Note
Version 3 is built on the Laravel AI SDK. The SDK stores conversations and messages, so the kit no longer ships its own Chat and Message models. Versions 1 and 2 were built on Prism. The last Prism release is the v2.0.1 tag.
- Multiple Conversations: Start a conversation, come back to it later, and switch between conversations
- Sidebar: The 30 most recent conversations, grouped by date. It collapses to a rail and stays in place while you navigate
- Search: Find a conversation by its title
- History: The AI SDK stores every conversation in the database
- Streaming: Replies appear while the model writes them, through Livewire streams
- Providers: OpenAI by default. Any provider in
config/ai.phpcan be used instead, including OpenAI-compatible gateways and local model servers - Tools: The model can call PHP classes as tools. Each call is shown with its arguments and result
- Tool Approval: A tool that changes something waits until the user approves or rejects the call
- FluxUI: Built from Flux components and styled with Tailwind CSS and its typography plugin
- Markdown: Replies are rendered with markdown-it, and code blocks are highlighted with highlight.js
Create a new Laravel application from the kit with the Laravel installer:
laravel new my-chat-app --using=kauffinger/livewire-chat-kitThen:
- Run migrations:
php artisan migrate - Install NPM dependencies:
npm install - Build assets:
npm run dev(ornpm run buildfor production)
The chat talks to OpenAI by default. Add your API key to .env:
OPENAI_API_KEY=your-openai-api-keyTo use another provider or model for the chat, add attributes to the agent. For example, Claude:
// In app/Ai/Agents/ChatAgent.php
use Laravel\Ai\Attributes\Model;
use Laravel\Ai\Attributes\Provider;
use Laravel\Ai\Enums\Lab;
#[Provider(Lab::Anthropic)]
#[Model('claude-sonnet-5-5')]
class ChatAgent implements Agent, Conversational, HasTools
{
// ...
}That provider's API key goes in .env as well, ANTHROPIC_API_KEY in this case.
To change the default provider without touching the agent, set AI_PROVIDER to any provider in config/ai.php. This is also how you point the chat at an OpenAI-compatible gateway or a local model server:
AI_PROVIDER=openai-compatible
OPENAI_COMPATIBLE_URL=https://your-gateway.example/v1
OPENAI_COMPATIBLE_API_KEY=your-gateway-key
OPENAI_COMPATIBLE_MODEL=your-modelOpen /dashboard. It redirects to your last conversation, or to a new one when you have none. From there you can:
- Start a new conversation from the sidebar
- Switch between conversations, or search them by title
- Ask the assistant to add two numbers, which calls the example
Sumtool - Ask the assistant to change the name on your profile, and approve or reject the tool call it asks for
flowchart TB
subgraph Browser
Input["Message input"]
Message["assistantMessage.js"]
end
subgraph Livewire
Show["Chats\Show"]
Sidebar["ChatSidebar"]
Index["Chats\Index"]
end
subgraph SDK["Laravel AI SDK"]
Agent["ChatAgent"]
Tools["Sum and UpdateProfileName"]
Store["ConversationStore"]
end
Provider["LLM provider"]
Database[("agent_conversations and agent_conversation_messages")]
Input -- "runAgent()" --> Show
Show -- "stream()" --> Agent
Agent <--> Provider
Agent --> Tools
Agent -- "stores each turn" --> Store
Show -- "history and pending approvals" --> Store
Store <--> Database
Show -- "stream events" --> Message
Show -. "conversation-updated" .-> Sidebar
Sidebar -- "User::conversations()" --> Database
Index -- "User::conversations()" --> Database
app/Ai/Agents/ChatAgent.php- The agent: instructions, tools, and conversation memoryapp/Ai/Tools/Sum.php- Example tool the agent can callapp/Ai/Tools/UpdateProfileName.php- Example tool that needs the user's approval before it runsapp/Livewire/Chats/Index.php- Paginate over all of your conversationsapp/Livewire/Chats/Show.php- Main chat component handling LLM streaming and message displayapp/Livewire/ChatSidebar.php- Conversation navigation and historyresources/js/components/assistantMessage.js- Alpine component that renders an assistant message, stored or streaming
The chat is one agent class. The Promptable trait adds prompt() and stream(). With RemembersConversations, the SDK loads the conversation before each prompt and stores the turn after it.
// app/Ai/Agents/ChatAgent.php
#[MaxSteps(5)]
class ChatAgent implements Agent, Conversational, HasTools
{
use Promptable;
use RemembersConversations;
/**
* Get the instructions that the agent should follow.
*/
public function instructions(): Stringable|string
{
return 'You are a helpful assistant.';
}
/**
* Get the tools available to the agent.
*
* @return list<Agent|Tool|ProviderTool>
*/
public function tools(): iterable
{
return [
new Sum,
new UpdateProfileName,
];
}
}Conversations and messages belong to the AI SDK. The app never creates them itself: the SDK creates a conversation and gives it a title when its first message is answered, and stores every turn after that.
erDiagram
users ||--o{ agent_conversations : "participant"
agent_conversations ||--o{ agent_conversation_messages : "messages"
users {
bigint id PK
string name
string email
}
agent_conversations {
string id PK
string participant_type
bigint participant_id
string title
}
agent_conversation_messages {
string id PK
string conversation_id FK
string agent
string role
text content
longtext steps
string status
}
The User model lists its conversations with the SDK's HasConversations trait, and the chat reads a conversation's history through the SDK's ConversationStore:
// app/Models/User.php
final class User extends Authenticatable
{
use HasConversations;
}
// app/Livewire/ChatSidebar.php
Auth::user()->conversations()->latest('updated_at')->limit(30)->get();
// app/Livewire/Chats/Show.php
resolve(ConversationStore::class)->paginateConversationMessages($this->conversationId, $this->messagesPerPage);A conversation can only be opened by the user it belongs to. Chats\Show aborts with a 403 for anyone else.
Titles are written by the provider's cheapest model. Set ai.conversations.generate_title to false in config/ai.php to use the start of the first message instead.
- Chat Interface: Real-time streaming with markdown rendering. Text is revealed at an even pace, new words fade in, and markdown that is still being written (half a bold word, link or table) is closed or hidden until it completes
- Status Row: Shows "Thinking…", the tool that is running, and the latest line of reasoning when the model streams it
- Tool Calls Display: Each tool call is a row that opens to show its arguments and result
- Tool Approval: A tool call that needs approval takes the place of the message input until you approve or reject it
- Message Input: Sits in the middle of a new conversation and docks to the bottom once it starts. It grows with the text, Enter sends and Shift+Enter starts a new line. While a reply streams, the send button becomes a stop button
- Code Blocks: Show their language and a copy button
- Earlier Messages: Loaded when you scroll to the top of a conversation
- Toast Notifications: Flux toasts, for example when the provider fails
sequenceDiagram
actor User
participant Browser
participant Show as Chats\Show
participant Agent as ChatAgent
participant Provider as LLM provider
participant Store as ConversationStore
User->>Browser: Types a message and presses Enter
Browser->>Browser: Shows the pending message
Browser->>Show: runAgent()
Show->>Agent: continueOrStart()->stream()
Agent->>Store: Reads the conversation so far
Agent->>Provider: Prompts with the history and the tools
loop Every stream event
Provider-->>Agent: Text, reasoning, tool call or tool result
Agent-->>Show: StreamEvent
Show-->>Browser: Streams the event to the assistant message
end
Agent->>Store: Stores the user message and the assistant's turn
Show-->>Browser: Renders the messages island
Show-->>Browser: Dispatches conversation-updated or redirects to the new conversation
- User Input: The user types a message and submits it
- Pending Message: The browser moves the message from the input into
pendingMessage, which shows it right away, and callsrunAgent()in the same request. This is thesendJavaScript action at the bottom ofshow.blade.php - LLM Streaming:
runAgent()continues the conversation withChatAgent, or starts one, and streams the response - Stream Handling:
Chats\Showstreams each of the SDK's events (text, reasoning, tool calls, results) to the browser as it arrives - UI Updates: The
assistantMessageAlpine component adds each event to the reply it is showing. It morphs the reply instead of replacing it, andresources/js/completeMarkdown.jsrepairs unfinished markdown. The stored messages live in a Livewire island, so sending a message does not render them again. When the turn ends before the reveal has caught up, the stored message continues it - Persistence: The AI SDK stores the user message and the assistant's turn when the response completes
- Stopping: The
stopJavaScript action cancels the streaming request and returns the message to the input, without another request. The SDK only stores a turn that completes, so a stopped reply is discarded - Failures: If the provider fails, the message returns to the input and a toast tells the user. A turn that failed after running tools is kept by the SDK and marked in the history
Steps 3 to 5 are one loop in Chats\Show. Here it is without the error handling:
// app/Livewire/Chats/Show.php
protected function streamAgent(Decisions|string $prompt): void
{
$stream = ChatAgent::make()
->continueOrStart($this->conversationId, as: Auth::user())
->stream($prompt);
foreach ($stream as $event) {
$this->stream(to: 'reply', content: $event->toArray());
}
$this->renderIsland('messages');
if ($this->conversationId === null) {
$this->redirectRoute('conversation.show', $stream->conversationId, navigate: true);
return;
}
$this->dispatch('conversation-updated');
}Each event reaches the browser in the SDK's own format, for example {"type": "text_delta", "delta": "Hello"}. The streaming assistant message listens for them with a Livewire message interceptor and adds each one to the message it renders:
// resources/js/components/assistantMessage.js
this.$wire.$interceptMessage(({ onStream }) => {
onStream(({ json }) => this.receive(json.content));
});
receive(event) {
switch (event.type) {
case 'text_delta':
this.message.content += event.delta;
break;
case 'reasoning_delta':
this.message.reasoning += event.delta;
break;
case 'tool_call':
// Adds the tool call to the message.
case 'tool_result':
// Adds the result to the tool call it belongs to.
}
}A stored message is the same component. It gets the whole message from Blade instead of from the stream:
{{-- resources/views/livewire/chats/show.blade.php --}}
<x-chat.assistant-message :message="$message" />
<x-chat.assistant-message streaming />- Definitions: Tools live in
app/Ai/Toolsand are registered inChatAgent::tools(). Create new ones withphp artisan make:tool - Execution: The model decides when to call a tool. The SDK runs it and returns the result to the model, for up to five steps per turn (
#[MaxSteps(5)]on the agent) - Display: Tool calls are shown while the reply streams and in the conversation history
- Approval: A tool that implements the SDK's
Approvablecontract pauses the turn. The chat shows the call with its arguments and resumes the turn once the user approves or rejects it
A tool is a description, a schema and a handle() method:
// app/Ai/Tools/Sum.php
class Sum implements Tool
{
/**
* Get the description of the tool's purpose.
*/
public function description(): Stringable|string
{
return 'Sums two numbers together.';
}
/**
* Execute the tool.
*/
public function handle(Request $request): Stringable|string
{
return (string) ($request->float('a') + $request->float('b'));
}
/**
* Get the tool's schema definition.
*/
public function schema(JsonSchema $schema): array
{
return [
'a' => $schema->number()->description('The first number to sum.')->required(),
'b' => $schema->number()->description('The second number to sum.')->required(),
];
}
}A tool that changes data can ask for the user's approval first. Implement Approvable and the SDK pauses the turn before the tool runs:
// app/Ai/Tools/UpdateProfileName.php
class UpdateProfileName implements Approvable, Tool
{
use InteractsWithApprovals;
/**
* Execute the tool.
*/
public function handle(Request $request): Stringable|string
{
$validated = $request->validate([
'name' => ['required', 'string', 'max:255'],
]);
Auth::user()->update($validated);
return "The profile name is now {$validated['name']}.";
}
/**
* Determine whether the tool needs approval for the given request.
*/
protected function needsApproval(Request $request): Approval|bool
{
return Approval::required(__('This will change the name on your profile.'));
}
}sequenceDiagram
actor User
participant Show as Chats\Show
participant Agent as ChatAgent
participant Tool as UpdateProfileName
participant Store as ConversationStore
User->>Show: Change my profile name to Ada Lovelace
Show->>Agent: stream()
Agent->>Tool: Does this call need approval?
Tool-->>Agent: Approval::required()
Agent->>Store: Stores the turn as paused
Show->>Store: pendingApprovalsFor()
Show-->>User: The approval takes the place of the message input
alt Approve
User->>Show: approveToolCalls()
Show->>Agent: stream(Decision::approveAll())
Agent->>Tool: handle()
else Reject
User->>Show: rejectToolCalls()
Show->>Agent: stream(Decision::rejectAll())
end
Agent->>Store: Stores the turn as completed
Show-->>User: The reply continues
The decision resumes the turn through the same streamAgent() method a message uses:
// app/Livewire/Chats/Show.php
public function approveToolCalls(): void
{
if ($this->pendingApprovals === []) {
return;
}
$this->streamAgent(Decision::approveAll());
}
public function rejectToolCalls(): void
{
if ($this->pendingApprovals === []) {
return;
}
$this->streamAgent(Decision::rejectAll(__('The user declined this action.')));
}Tests fake the agent with ChatAgent::fake(), so they never call a provider. ConversationFactory and ConversationMessageFactory build the SDK's models:
// tests/Feature/Livewire/Chats/ShowTest.php
it('allows sending messages', function (): void {
ChatAgent::fake(['Hello, human!']);
$user = User::factory()->create();
$conversation = ConversationFactory::new()->recycle($user)->create();
actingAs($user);
livewire(Show::class, ['conversation' => $conversation])
->set('pendingMessage', 'Hello, world!')
->call('runAgent')
->assertDispatched('conversation-updated');
ChatAgent::assertPrompted('Hello, world!');
expect($conversation->messages()->orderBy('id')->get())
->toHaveCount(2)
->sequence(
fn ($message) => $message->role->toBe('user')->content->toBe('Hello, world!'),
fn ($message) => $message->role->toBe('assistant')->content->toBe('Hello, human!'),
);
});A tool call that waits for approval is faked the same way:
ChatAgent::fake([
AgentResponse::fakeWithPendingApprovals([
new PendingApproval(id: 'call_1', tool: 'UpdateProfileName', arguments: ['name' => 'Ada King']),
]),
'All done.',
]);Browser tests in tests/Browser drive Chrome through Pest's browser plugin and cover what only runs in JavaScript: sending with Enter, the rendered markdown, tool call details and loading earlier messages. They run with the rest of the suite and need Playwright's Chromium and built assets:
npx playwright install chromium
npm run buildPest's test server hands a streamed reply to the browser in one piece, so the browser tests check the finished turn rather than the token stream.
The tests run with Pest. PHP is formatted with Laravel Pint and Rector, and JavaScript, CSS and Blade with Prettier:
composer test
composer formatToasts are Flux toasts. The <flux:toast /> element lives in resources/views/components/layouts/app/sidebar.blade.php.
use Flux\Flux;
Flux::toast(
variant: 'success',
heading: 'Changes saved.',
text: 'You can always update this in your settings.',
);<flux:button
x-on:click="
$flux.toast({
variant: 'success',
heading: 'Changes saved.',
text: 'You can always update this in your settings.',
})
"
>
Show Success Toast
</flux:button>variant: 'success' | 'warning' | 'danger'heading: The title (optional)text: The messageduration: Auto-dismiss after milliseconds (default: 5000, use 0 to keep it open)
Bug reports, feature suggestions and pull requests are welcome in the GitHub repository.
This project is open-sourced software licensed under the MIT license.