Why I Built an AI Agent Framework for Laravel (And Why PHP Deserves AI Too) 🚀

Aaron Lumsden — Thu, 14 Aug 2025 11:05:38 +0000

For over a decade, I've been building with Laravel. It's been my go-to framework for everything from simple APIs to complex SaaS platforms. But lately, I've felt like a kid with my face pressed against the candy store window, watching the Python developers have all the AI fun.

Every time I wanted to build an AI agent, I'd have to context-switch to Python. LangChain, AutoGPT, CrewAI – they're all amazing, but they're not PHP. They're not Laravel. And that constant switching between ecosystems was killing my productivity.

So I did what any reasonable developer would do after one too many late nights wrestling with Python virtual environments... I built my own AI agent framework for Laravel. 😅

Meet Vizra ADK – the AI Agent Development Kit that brings true agentic capabilities home to Laravel.

The Problem That Kept Me Up at Night 🌙

Picture this: You're building a Laravel app that needs an intelligent customer support agent. In the Python world, you'd spin up a separate service, set up API endpoints, manage different dependency managers, deployment pipelines, and pray that your PHP app and Python agent play nicely together.

But what if your agent could just... be Laravel? What if it could use Eloquent models directly? Queue jobs? Fire events? What if building an AI agent was as simple as extending a base class?

That's the itch I needed to scratch.

The "Aha!" Moment 💡

The breakthrough came when I realized that AI agents don't need to be complicated. At their core, they're just:

A persona (instructions and behavior)
Tools (things they can do)
Memory (context and history)
A brain (the LLM)

That's it. And Laravel already has amazing patterns for all of these!

Your First Agent in Under 5 Minutes ⚡

With Vizra ADK, you can have a working AI agent in literally three commands:

composer require vizra/vizra-adk
php artisan vizra:install
php artisan vizra:make:agent CustomerSupportAgent

Now let's look at what an actual agent looks like:

<?php

namespace App\Agents;

use Vizra\VizraADK\Agents\BaseLlmAgent;

class CustomerSupportAgent extends BaseLlmAgent
{
    protected string $name = 'customer_support';

    protected string $description = 'Helps customers with their inquiries';

    protected string $instructions = 'You are a friendly customer support assistant.
        Always be helpful and provide accurate information.';

    protected string $model = 'gpt-4o';

    protected array $tools = [
        OrderLookupTool::class,
        RefundProcessorTool::class,
    ];
}

That's it. That's a fully functional AI agent. No registration needed – Vizra ADK auto-discovers your agents. You can start using it immediately:

$response = CustomerSupportAgent::run('I need help with order #12345')
    ->forUser($user)
    ->go();

Or chat with it via the command line:

php artisan vizra:chat customer_support

Vizra also has a bneautiful chat UI built in that you can use to chat with your agent.

The Secret Sauce: Tools That Feel Like Laravel 🛠️

This is where things get really exciting. In Python frameworks, giving your agent access to your database or business logic often means building complex bridges. With Vizra ADK, your tools can directly use Eloquent:

<?php

namespace App\Tools;

use Vizra\VizraADK\Contracts\ToolInterface;
use Vizra\VizraADK\System\AgentContext;
use App\Models\Order;

class OrderLookupTool implements ToolInterface
{
    public function definition(): array
    {
        return [
            'name' => 'order_lookup',
            'description' => 'Look up order information by order ID',
            'parameters' => [
                'type' => 'object',
                'properties' => [
                    'order_id' => [
                        'type' => 'string',
                        'description' => 'The order ID to look up',
                    ],
                ],
                'required' => ['order_id'],
            ],
        ];
    }

    public function execute(array $arguments, AgentContext $context): string
    {
        // Just use Eloquent like you always do!
        $order = Order::find($arguments['order_id']);

        if (!$order) {
            return json_encode(['error' => 'Order not found']);
        }

        // Your agent now has access to your actual business logic
        $order->load(['items', 'customer', 'shipping']);

        return json_encode([
            'order_id' => $order->id,
            'status' => $order->status,
            'total' => $order->total,
            'customer' => $order->customer->name,
            'items' => $order->items->map(fn($item) => [
                'name' => $item->product->name,
                'quantity' => $item->quantity,
                'price' => $item->price,
            ]),
        ]);
    }
}

Your existing Laravel code IS the agent's toolkit. No API layers. No serialization headaches. Just PHP. 🎉

Memory That Persists (Because Context Matters) 🧠

One of the coolest features is how Vizra ADK handles memory and context. Every conversation is automatically persisted, and agents can maintain state across interactions:

// The agent remembers previous conversations
$response = PersonalShoppingAssistantAgent::run('Find me a gift for my mom')
    ->forUser($user)
    ->withSession($sessionId)
    ->withContext([
        'budget' => 200,
        'occasion' => 'birthday',
    ])
    ->go();

// Later in the conversation...
$response = PersonalShoppingAssistantAgent::run('She loves gardening')
    ->forUser($user)
    ->withSession($sessionId)  // Same session = continued context
    ->go();
// The agent remembers the budget, occasion, AND now knows about gardening!

The AgentContext class manages all of this elegantly, passing state between your agent and its tools:

class CartManagerTool implements ToolInterface
{
    public function execute(array $arguments, AgentContext $context): string
    {
        // Get current cart from context
        $cart = $context->getState('cart', []);
        $budget = $context->getState('budget');

        // Add item to cart
        $cart[] = [
            'id' => uniqid('item_'),
            'name' => $arguments['item_name'],
            'price' => $arguments['item_price'],
        ];

        // Update context state
        $context->setState('cart', $cart);
        $context->setState('total_spent', array_sum(array_column($cart, 'price')));

        return json_encode([
            'success' => true,
            'cart_total' => $context->getState('total_spent'),
            'remaining_budget' => $budget - $context->getState('total_spent'),
        ]);
    }
}

Multi-Model Support (Because Vendor Lock-in Sucks) 🔄

Thanks to the amazing Prism PHP library, Vizra ADK works with all major LLM providers out of the box:

// Use OpenAI
protected string $model = 'gpt-4o';

// Or Claude
protected string $model = 'claude-3-opus';

// Or Gemini
protected string $model = 'gemini-2.0-flash';

// Or local Ollama
protected string $model = 'llama3:latest';

Switch providers with just an environment variable. Your code doesn't change. I learned this lesson the hard way with payment gateways years ago – never again! 😂

The Laravel Advantage 🏆

Here's what makes Vizra ADK special for Laravel developers:

1. Eloquent Integration

Your agents can directly query your database, update models, and leverage all your existing scopes and relationships.

2. Queue Integration

Long-running agent tasks? Just queue them:

CustomerSupportAgent::run($message)
    ->forUser($user)
    ->async()
    ->onQueue('agents')
    ->go();

3. Event System

Agents fire Laravel events at key points:

Event::listen(AgentExecutionFinished::class, function ($event) {
    Log::info('Agent completed', [
        'agent' => $event->agent,
        'duration' => $event->duration,
        'tokens_used' => $event->tokensUsed,
    ]);
});

4. Artisan Commands

Everything is accessible via Artisan:

php artisan vizra:agents          # List all discovered agents
php artisan vizra:chat agent_name # Interactive chat
php artisan vizra:trace abc-123   # Debug execution traces
php artisan vizra:dashboard       # Web UI for testing

5. Evaluation Framework

Test your agents at scale with the built-in evaluation system:

php artisan vizra:make:eval CustomerSupportEval

Then define your test cases in CSV and run automated evaluations:

class CustomerSupportEvaluation extends BaseEvaluation
{
    public string $csvPath = 'app/Evaluations/data/customer_support_tests.csv';

    public function evaluateRow(array $csvRowData, string $llmResponse): array
    {
        // Validate the agent's response
        $this->assertResponseContains($llmResponse, 'help');
        $this->assertResponseHasPositiveSentiment($llmResponse);

        // Or use LLM-as-Judge for subjective evaluation
        $this->judge($llmResponse)
            ->using(QualityJudgeAgent::class)
            ->expectMinimumScore(7.0);

        return parent::evaluateRow($csvRowData, $llmResponse);
    }
}

Real-World Example: Multi-Agent Workflows 🔄

Where Vizra ADK really shines is when you need multiple agents working together:

use Vizra\VizraADK\Facades\Workflow;

// Sequential workflow - each agent processes results from the previous
$workflow = Workflow::sequential()
    ->then(ValidateOrderAgent::class)      // Checks inventory, pricing
    ->then(PaymentProcessingAgent::class)  // Handles payment
    ->then(FulfillmentAgent::class)        // Creates shipping labels
    ->then(NotificationAgent::class);       // Emails customer

// Execute the entire workflow
$result = $workflow->execute($orderData, $context);

// Or use parallel execution for independent tasks
$notifications = Workflow::parallel([
    EmailAgent::class,
    SmsAgent::class,
    SlackAgent::class
])->waitForAll()->execute($message, $context);

Each agent can access the results from previous agents, creating complex, intelligent workflows that would be a nightmare to orchestrate across language boundaries.

The Debug Experience That Doesn't Suck 🐛

I spent weeks debugging AI agents with just print statements before building proper tracing into Vizra ADK:

php artisan vizra:trace abc-123-xyz

This shows you:

Every LLM call with prompts and responses
Tool executions with inputs and outputs
Token usage and costs
Execution timing for performance optimization
Memory updates and context changes

Or use the built-in web dashboard:

php artisan vizra:dashboard

Now you get a beautiful Livewire-powered interface where you can chat with your agents, see real-time traces, and monitor performance. Finding bottlenecks went from 2 hours to 2 minutes. 🎯

Early Success & Community Response 💙

Since launching Vizra ADK:

65 downloads in the first week
49 stars on GitHub
Amazing feedback from the Laravel community
Several production deployments already!

But what excites me most is seeing what people are building:

A legal document analyzer that uses existing Laravel permissions
A code review bot that integrates with existing CI/CD pipelines
An intelligent inventory manager that predicts stock needs
A customer service bot that actually understands context

What's Next? 🚀

I'm actively working on:

Cloud platform for managed evaluations and monitoring

Join Me on This Journey 🤝

Look, I get it. "Another framework" might make you roll your eyes. But if you're a Laravel developer who's been watching the AI revolution from the sidelines, or struggling with Python integration, give Vizra ADK a try.

It's MIT licensed, fully open source, and built by someone who's been in the Laravel trenches for over a decade. I built this because I needed it, and I'm betting you do too.

composer require vizra/vizra-adk
php artisan vizra:install
# Join me on this journey

GitHub: https://github.com/vizra-ai/vizra-adk

Documentation: https://vizra.ai/docs

X: @aaronlumsden

Let's show the world that PHP deserves a seat at the AI table. Because Laravel developers shouldn't have to learn Python just to build intelligent applications.

We already have the best web framework. Now we have AI agents to match. 🚀

What are you building with AI? Have you felt the PHP/Python divide? I'd love to hear your thoughts in the comments!

Video courses to improve your web development skills

Aaron Lumsden — Sat, 27 Apr 2019 09:58:41 +0000

Hey there I've created a new website where any one can learn web development for free. I'd love to hear your thoughts & feedback on it.

Courses include Laravel, Vue.js, JavaScript, React.js, Angular.js, Node.js, Python and PHP. Let me know what you think? 👍

https://codevideos.co/

DEV Community: Aaron Lumsden