PHPackages                             alidaaer/laravel-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. alidaaer/laravel-ai-agent

ActiveLibrary[Utility & Helpers](/categories/utility)

alidaaer/laravel-ai-agent
=========================

Give your Laravel app a brain, safely. Build AI Agents that can execute real actions in your application.

v1.0.0(4mo ago)286734MITPHPPHP ^8.2

Since Feb 20Pushed 4mo agoCompare

[ Source](https://github.com/alidaaer/Laravel-AI-Agent)[ Packagist](https://packagist.org/packages/alidaaer/laravel-ai-agent)[ Docs](https://github.com/alidaaer/laravel-ai-agent)[ RSS](/packages/alidaaer-laravel-ai-agent/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (6)Versions (3)Used By (0)

 [![Laravel AI Agent Logo](logo.png)](logo.png)

Laravel AI Agent
================

[](#laravel-ai-agent)

 **🧠 Give your Laravel app a brain, safely.**

 [![Latest Version](https://camo.githubusercontent.com/2470b217d135ebfb308a459efc06d03689772424e5bae412db4543b13ef62bed/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616c6964616165722f6c61726176656c2d61692d6167656e742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/alidaaer/laravel-ai-agent) [![License](https://camo.githubusercontent.com/d381278cd2378bd2bdba004d033802d5ca55396e4b662b233f362392a81b21cb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f616c6964616165722f6c61726176656c2d61692d6167656e742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/alidaaer/laravel-ai-agent) [![PHP Version](https://camo.githubusercontent.com/958da9c49ec5d3a994a485695225cd5ec57cc5b1e093b49892f65dd7ae8db3a9/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e322d3838393242462e7376673f7374796c653d666c61742d737175617265)](https://php.net) [![Laravel Version](https://camo.githubusercontent.com/181d0ffee70d9ffe131375f9555814f48adf6fcfd42981619ded90b89a196623/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d25334525334431302e302d4646324432302e7376673f7374796c653d666c61742d737175617265)](https://laravel.com)

 Build AI Agents that execute **real actions** in your Laravel application with minimal code.

---

Laravel AI Agent is the ultimate **Laravel AI package** for building intelligent automation. Transform your Laravel app with **AI-powered agents** that can understand natural language and execute PHP methods directly. Perfect for **Laravel GPT integration**, **AI automation**, and **function calling**. This Laravel AI solution works with OpenAI, Anthropic Claude, Gemini, and more - making it the most flexible **AI assistant for Laravel**.

✨ Why Laravel AI Agent?
-----------------------

[](#-why-laravel-ai-agent)

FeatureDescription🚀 **Zero Boilerplate**Turn any method into an AI tool with a single attribute🧠 **Smart Auto-Inference**Auto-generates descriptions and infers types from parameter names💬 **Chat Widget**Beautiful, customizable Web Component - just drop it in!🔌 **Multi-Provider**OpenAI, Anthropic Claude, Google Gemini, DeepSeek, OpenRouter💾 **Memory**AI-powered summarization with smart pointer tracking — session or database📊 **Markdown Responses**Tables, formatting, and rich text in chat⚡ **Smart Returns**`view()`, `redirect()`, `Model` — AI understands them all🤖 **Multi-Agent**Class-based agents with per-method access control🛡️ **Security Built-in**Prompt injection detection, XSS prevention, secret redaction🎯 **Laravel Native**Feels like part of the framework---

📦 Installation
--------------

[](#-installation)

```
composer require alidaaer/laravel-ai-agent
php artisan vendor:publish --tag=ai-agent-config
```

Add to your `.env`:

```
# AI Driver (openai, anthropic, gemini, deepseek, openrouter)
AI_AGENT_DRIVER=openai
AI_AGENT_API_KEY=sk-...
AI_AGENT_MODEL=gpt-4o-mini
```

Run migrations for conversation history:

```
php artisan migrate
```

---

🚀 Quick Start
-------------

[](#-quick-start)

### 1. Add the Chat Widget ⚡

[](#1-add-the-chat-widget-)

Drop it into any Blade view — **routes are auto-registered!**

```
@aiAgentWidget

```

**Open the page, click the bubble, start talking.** You already have a working AI chatbot! 🎉

All widget settings (theme, language, position, etc.) are read from `config/ai-agent.php`:

```
'widget' => [
    'theme' => 'dark',
    'rtl' => false,
    'primary_color' => '#6366f1',
    'position' => 'bottom-right',
    'system_prompt' => 'You are a helpful shop assistant.',
],
```

> 💡 The `system_prompt` is set in config (not HTML) so it stays hidden from the client.

### 2. Give AI Your Tools (Zero-Config!)

[](#2-give-ai-your-tools-zero-config)

```
use LaravelAIAgent\Attributes\AsAITool;

class ProductService
{
    #[AsAITool]  // Description auto-generated: "List products" ✨
    public function listProducts(): array
    {
        return Product::all()->toArray();
    }

    #[AsAITool]  // Types inferred: $price→number, $stock→integer
    public function addProduct(string $name, float $price, int $stock = 0): array
    {
        return Product::create(compact('name', 'price', 'stock'))->toArray();
    }
}
```

Place it **anywhere in `app/`** — the package auto-discovers all `#[AsAITool]` methods. Now say *"Add a product called iPhone for $999"* and it actually does it! 🚀

> 🤖 **Need custom agents?** Create dedicated agents with `php artisan make:agent` — see [Multi-Agent System](#-multi-agent-system).

---

💬 Chat Widget Component
-----------------------

[](#-chat-widget-component)

A beautiful, drop-in Web Component for AI chat — with conversations, i18n, and stop button built-in.

### Full-Featured Example

[](#full-featured-example)

```
{{-- Reads all settings from config/ai-agent.php --}}
@aiAgentWidget

```

Or use the PHP helper directly with overrides:

```
{!! \LaravelAIAgent\Widget::render(['theme' => 'light', 'lang' => 'ar']) !!}

```

### All Options

[](#all-options)

AttributeDescriptionDefault`endpoint`Chat API URLRequired`stream`Enable SSE streaming (boolean)—`history-endpoint`Load conversation history + conversations sidebar—`persist-messages`Keep messages across page reloads (boolean)—`theme``light` or `dark``dark``lang`Language: `en`, `ar`, `fr`, `es`, `zh``en``rtl`Right-to-left mode (boolean)Auto for `ar``title`Header title`AI Assistant``subtitle`Header subtitle—`welcome-message`First bot message—`placeholder`Input placeholder`Type your message...``primary-color`Theme color`#6366f1``position``bottom-right`, `bottom-left`, `top-right`, `top-left``bottom-right``width`Widget width`400px``height`Widget height`600px``button-icon`Floating button icon (URL or emoji)`💬``button-size`Floating button size`56px`### Features

[](#features)

- ✅ **SSE Streaming** — Real-time streaming with tool execution progress
- ✅ **Markdown Support** — Tables, bold, code blocks with copy button, lists
- ✅ **Voice Input** — Built-in Web Speech API microphone button
- ✅ **i18n** — 5 languages built-in (EN, AR, FR, ES, ZH)
- ✅ **RTL Support** — Auto-detected for Arabic, Hebrew, Farsi
- ✅ **Stop Button** — Cancel AI responses mid-generation
- ✅ **Conversations Sidebar** — Switch between past conversations (isolated per agent)
- ✅ **Keyboard Shortcuts** — Escape to close, Enter to send, Shift+Enter for new line
- ✅ **Mobile Responsive** — Full-screen on mobile
- ✅ **No Dependencies** — Pure Web Component

---

🔧 Chat API
----------

[](#-chat-api)

Routes are **auto-registered** — no setup needed! The widget works out of the box with:

```
POST /ai-agent/chat           → General chat
GET  /ai-agent/history        → Conversation history
GET  /ai-agent/conversations  → List conversations

```

Need a custom endpoint? Easy:

```
// routes/api.php
Route::post('/my-chat', function () {
    $response = Agent::conversation(request('conversation_id'))
        ->system('You are a helpful shop assistant')
        ->tools([ProductService::class])
        ->chat(request('message'));

    return response()->json(['response' => $response]);
});
```

---

🛠️ Creating Tools
-----------------

[](#️-creating-tools)

### Zero-Config (Recommended)

[](#zero-config-recommended)

```
#[AsAITool]  // Description: "List Products" (from method name)
public function listProducts(): array { }

#[AsAITool]  // Description: "Add Product"
public function addProduct(string $name, float $price): array { }
```

### With Custom Description

[](#with-custom-description)

```
#[AsAITool('Search for products by name or category')]
public function search(string $query): array { }
```

### With Custom Parameters

[](#with-custom-parameters)

The package auto-discovers parameters from type hints. But if your method uses `Request` or you want more control, define them manually with `name:type` syntax:

```
#[AsAITool(
    description: 'Update product details',
    params: [
        'id:integer' => 'Product ID to update',
        'name' => 'New product name',          // type auto-inferred as string
        'price:number' => 'New price in USD',
    ]
)]
public function updateProduct(Request $request): array
{
    $product = Product::findOrFail($request->input('id'));
    $product->update($request->only(['name', 'price']));
    return ['success' => true, 'product' => $product->toArray()];
}
```

Supported types: `string`, `integer`, `number`, `boolean`, `array`. Without `:type`, the type is inferred from the parameter name (`id` → integer, `price` → number).

> 💡 **When to use `params`?** Only when auto-discovery isn't enough — e.g., dynamic `Request` inputs, or when you want custom descriptions for the AI.

### Smart Type Inference

[](#smart-type-inference)

No type hints? We infer from names:

Parameter NameInferred Type`$id`, `$productId`, `$userId``integer``$price`, `$total`, `$amount``number``$isActive`, `$hasItems`, `$enabled``boolean``$items`, `$products`, `$users``array`Other`string`---

⚡ Smart Return Handling
-----------------------

[](#-smart-return-handling)

**Use your existing methods as AI tools — no refactoring needed.**

The agent automatically understands any return type: `view()`, `redirect()`, `Model`, `Collection`, `JsonResponse`, and even catches exceptions and validation errors gracefully.

### Zero-Config — It Just Works

[](#zero-config--it-just-works)

```
#[AsAITool]
public function showProduct(int $id)
{
    return view('product.show', ['product' => Product::findOrFail($id)]);
    // AI receives: {"product": {"id": 1, "name": "iPhone", "price": 999}} ✨
}

#[AsAITool]
public function activateProduct(int $id)
{
    Product::findOrFail($id)->update(['is_active' => true]);
    return redirect()->back()->with('message', 'Product activated!');
    // AI receives: {"message": "Product activated!"} ✨
}
```

### Exceptions & Validation — Handled Automatically

[](#exceptions--validation--handled-automatically)

```
#[AsAITool]
public function createProduct(string $name, float $price)
{
    $validator = Validator::make(compact('name', 'price'), [
        'name' => 'required|min:3',
        'price' => 'required|numeric|min:0.01',
    ]);

    if ($validator->fails()) throw new ValidationException($validator);
    // AI tells the user: "Product name must be at least 3 characters" 🛡️

    return Product::create(compact('name', 'price'))->toArray();
}
```

### `isAICall()` — Full Control When You Need It

[](#isaicall--full-control-when-you-need-it)

Customize responses for AI vs Web with a single helper:

```
#[AsAITool]
public function listProducts()
{
    $products = Product::all();

    if (isAICall()) {
        return ['count' => $products->count(), 'products' => $products->toArray()];
    }

    return view('products.index', compact('products'));
}
```

> **One method, two audiences.** Web users get a Blade view, AI gets structured data.

Return TypeWhat AI Receives`view('...', $data)`The `$data` variables directly`redirect()->with('message', '...')``{"message": "..."}``Eloquent Model``model->toArray()``Collection``collection->toArray()``JsonResponse`The JSON data`ValidationException`Error messages in user's language`Any Exception`Error message for AI to report---

🔌 Providers
-----------

[](#-providers)

```
// OpenAI (default)
Agent::driver('openai')->chat("Hello");

// Google Gemini
Agent::driver('gemini')->chat("Hello");

// Anthropic Claude
Agent::driver('anthropic')->chat("Hello");

// OpenRouter (100+ models via single API)
Agent::driver('openrouter')->model('anthropic/claude-3.5-sonnet')->chat("Hello");

// Specific model override
Agent::driver('openai')->model('gpt-4o')->chat("Hello");
```

---

🤖 Multi-Agent System
--------------------

[](#-multi-agent-system)

Create dedicated agent classes with isolated tools, permissions, and conversations.

### 1. Create an Agent

[](#1-create-an-agent)

```
php artisan make:agent ShopAgent
php artisan make:agent AdminAgent
```

This generates a class in `app/AI/Agents/` and **auto-registers** it in `config/ai-agent.php`.

```
// app/AI/Agents/ShopAgent.php
class ShopAgent extends BaseAgent
{
    public function instructions(): string
    {
        return 'You are a friendly shop assistant. Help customers browse and order.';
    }

    public function tools(): array
    {
        return [\App\Services\ShopService::class];
    }

    // Optional: customize driver, model, middleware, widget...
    // public function driver(): ?string { return 'openai'; }
    // public function model(): ?string { return 'gpt-4o-mini'; }
    // public function routeMiddleware(): array { return ['web', 'auth']; }
}
```

### 2. Scope Tools Per Agent

[](#2-scope-tools-per-agent)

Use class references for IDE autocompletion and refactor safety:

```
use App\AI\Agents\AdminAgent;

class OrderService
{
    #[AsAITool]                                        // 👈 All agents see this
    public function listOrders(): array { /* ... */ }

    #[AsAITool(agents: [AdminAgent::class])]           // 👈 Admin only
    public function deleteOrder(int $id) { /* ... */ }

    #[AsAITool(agents: [AdminAgent::class])]           // 👈 Admin only
    public function advancedStats() { /* ... */ }
}
```

**Rule:** No `agents` param = available to **all** agents. Explicit list = restricted.

### 3. Auto-Generated Endpoints

[](#3-auto-generated-endpoints)

Each agent gets its own isolated routes — **automatically**:

```
POST   /ai-agent/shop/chat           → Chat with ShopAgent
POST   /ai-agent/shop/chat-stream    → SSE streaming chat
GET    /ai-agent/shop/conversations  → List ShopAgent conversations only
GET    /ai-agent/shop/history        → Conversation history
DELETE /ai-agent/shop/history        → Clear conversation

POST   /ai-agent/admin/chat          → Chat with AdminAgent (sees deleteOrder, advancedStats)
GET    /ai-agent/admin/conversations → List AdminAgent conversations only

```

**Conversations are isolated per agent** — each agent sees only its own conversation history.

### 4. Add Widget to Blade

[](#4-add-widget-to-blade)

Each agent renders its own fully-configured widget:

```
// In any Blade view
{!! \App\AI\Agents\ShopAgent::widget() !!}
{!! \App\AI\Agents\AdminAgent::widget() !!}

```

Each widget automatically uses the correct endpoints, theme, language, and position defined in the agent's `widgetConfig()`.

### 5. Customize Widget Appearance

[](#5-customize-widget-appearance)

```
class AdminAgent extends BaseAgent
{
    public function widgetConfig(): array
    {
        return [
            'title' => 'Admin AI',
            'theme' => 'light',
            'lang' => 'ar',
            'primary_color' => '#ef4444',
            'position' => 'bottom-left',
        ];
    }
}
```

### 6. Mobile / API Usage

[](#6-mobile--api-usage)

```
// Flutter example
final response = await http.post(
  Uri.parse('https://yourapp.com/ai-agent/shop/chat'),
  body: {'message': 'Show my orders', 'conversation_id': conversationId},
);
```

> **No agents?** Everything works without agents — use the generic `/ai-agent/chat` endpoint with the widget directly.

---

💾 Conversation Memory
---------------------

[](#-conversation-memory)

```
// Conversations are remembered!
Agent::conversation('user-123')
    ->tools([OrderService::class])
    ->chat("Show my orders");

// Later...
Agent::conversation('user-123')
    ->chat("Cancel the last one");
// AI remembers the context!
```

**Smart Memory Management:**

- After every `summarize_after` messages, the AI generates a concise summary of older messages
- Messages are **never deleted** until reaching `max_messages` hard limit
- The LLM receives: `[summary of old context]` + `[last N recent messages]` + `[new message]`
- Falls back to manual summarization if AI summarization fails
- Disable AI summarization with `AI_AGENT_AI_SUMMARY=false` in `.env`

---

⚙️ Configuration
----------------

[](#️-configuration)

```
// config/ai-agent.php
return [
    'default' => env('AI_AGENT_DRIVER', 'openai'),
    'verify_ssl' => env('AI_AGENT_VERIFY_SSL', false),

    'drivers' => [
        'openai' => [
            'api_key' => env('OPENAI_API_KEY'),
            'model' => env('OPENAI_MODEL',env('AI_AGENT_MODEL','gpt-4o-mini')),
        ],
        'anthropic' => [ /* ... */ ],
        'gemini'    => [ /* ... */ ],
        'deepseek'  => [ /* ... */ ],
        'openrouter' => [ /* ... */ ],
    ],

    'discovery' => [
        'paths' => [app_path()],    // Scans all app/ by default
        'cache' => true,            // Cache discovered tools
    ],

    'memory' => [
        'driver' => env('AI_AGENT_MEMORY', 'session'),
        'summarize_after' => 10,    // AI-summarize every N messages
        'max_messages' => 100,      // Hard limit — delete oldest beyond this
        'recent_messages' => 4,     // Send last N messages to LLM
        'ai_summarization' => true, // Use AI for smart summaries
    ],

    'agents' => [
        \App\AI\Agents\ShopAgent::class,
        \App\AI\Agents\AdminAgent::class,
    ],

    'security' => [
        'enabled' => true,          // All security on by default
        'max_tool_calls_per_request' => 10,
        'max_iterations' => 10,
    ],
];
```

> 📖 See [Full Documentation](documentation.md) for all configuration options.

---

📡 Events
--------

[](#-events)

```
use LaravelAIAgent\Events\ToolCalled;
use LaravelAIAgent\Events\ToolExecuted;

Event::listen(ToolCalled::class, function ($event) {
    Log::info("AI called: " . $event->tool['name']);
});

Event::listen(ToolExecuted::class, function ($event) {
    Log::info("Result: " . json_encode($event->result));
});
```

---

📖 Full Example
--------------

[](#-full-example)

```
// 1️⃣ Service with tools — place anywhere in app/
class ShopService
{
    #[AsAITool]
    public function listProducts(): array {
        return Product::all()->toArray();
    }

    #[AsAITool]
    public function addProduct(string $name, float $price): array {
        return Product::create(compact('name', 'price'))->toArray();
    }
}
```

```
# 2️⃣ Create an agent
php artisan make:agent ShopAgent
```

```
// 3️⃣ Drop the widget in Blade — routes are auto-registered!
{!! \App\AI\Agents\ShopAgent::widget() !!}

```

**That's it.** Tools are auto-discovered, routes are auto-registered, conversations are isolated per agent, memory is auto-managed. 🎉

---

📖 Documentation
---------------

[](#-documentation)

For the full detailed documentation — including all configuration options, security features, event system, streaming, and more — see **[documentation.md](documentation.md)**.

---

🤝 Contributing
--------------

[](#-contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License
---------

[](#-license)

The MIT License (MIT). See [License File](LICENSE.md) for more information.

---

 Made with ❤️ for Laravel developers

###  Health Score

43

—

FairBetter than 89% of packages

Maintenance76

Regular maintenance activity

Popularity28

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity48

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 ~0 days

Total

2

Last Release

132d ago

Major Versions

v0.1.0-beta → v1.0.02026-02-21

### Community

Maintainers

![](https://www.gravatar.com/avatar/b0cd2a4d254227b6dac14dae5ea6df97bacbabf3f54fd2295c26190b84da4699?d=identicon)[alidaaer](/maintainers/alidaaer)

---

Top Contributors

[![alidaaer](https://avatars.githubusercontent.com/u/64861445?v=4)](https://github.com/alidaaer "alidaaer (21 commits)")

---

Tags

laravelaiopenaiAgenttoolsGeminillmanthropicdeepseekfunction-calling

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/alidaaer-laravel-ai-agent/health.svg)

```
[![Health](https://phpackages.com/badges/alidaaer-laravel-ai-agent/health.svg)](https://phpackages.com/packages/alidaaer-laravel-ai-agent)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M131](/packages/roots-acorn)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

77022.3M151](/packages/laravel-mcp)[propaganistas/laravel-disposable-email

Disposable email validator

6023.0M7](/packages/propaganistas-laravel-disposable-email)[toin0u/geocoder-laravel

Geocoder Service Provider for Laravel

7615.4M17](/packages/toin0u-geocoder-laravel)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)