Skip to main content
LarAgent dispatches Laravel events at key points during agent execution. This allows you to hook into the agent lifecycle using Laravel’s native event system for logging, monitoring, analytics, and more.

​
Quickstart

1

Create a listener

php artisan make:listener AgentListener
2

Import the event and implement the handler

namespace App\Listeners;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;
use LarAgent\Events\AgentInitialized;

class AgentListener
{
    public function __construct()
    {
        //
    }

    public function handle(AgentInitialized $event): void
    {
        // Access the agent DTO
        dd('Agent has been initialized:', $event->agentDto);
    }
}
3

Register the event listener

Open app/Providers/AppServiceProvider.php and register the event with its listener:
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Illuminate\Support\Facades\Event;
use LarAgent\Events\AgentInitialized;
use App\Listeners\AgentListener;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        //
    }

    public function boot(): void
    {
        Event::listen(
            AgentInitialized::class,
            AgentListener::class
        );
    }
}
Now whenever an agent is initialized, your handle method will be executed.

​
AgentDTO Structure

Each event that includes agentDto uses the following Data Transfer Object structure:
namespace LarAgent\Core\DTO;

class AgentDTO
{
    public function __construct(
        public readonly string $provider,
        public readonly string $providerName,
        public readonly ?string $message,
        public readonly array $tools = [],
        public readonly ?string $instructions = null,
        public readonly ?array $responseSchema = [],
        public readonly array $configuration = []
    ) {}

    public function toArray(): array
    {
        return [
            'provider' => $this->provider,
            'providerName' => $this->providerName,
            'message' => $this->message,
            'tools' => $this->tools,
            'instructions' => $this->instructions,
            'responseSchema' => $this->responseSchema,
            'configuration' => $this->configuration,
        ];
    }
}

​
Available Events

LarAgent provides events across different categories:

Agent Events

Lifecycle events for agent initialization, conversation flow, and termination.

Context Events

Events for context storage operations and state changes.

History Events

Events for chat history operations and message handling.

​
Events vs Agent Hooks

LarAgent provides two ways to customize behavior:
FeatureAgent HooksLaravel Events
DefinitionOverride methods in agent classSeparate listener classes
ScopeSingle agent classApplication-wide
Async supportNoYes (via queues)
Modify behaviorCan return false to haltObserve only
Use caseAgent-specific logicCross-cutting concerns
Use agent hooks for agent-specific customizations that need to modify behavior. Use Laravel events for logging, monitoring, analytics, and other cross-cutting concerns that should be decoupled from your agent classes.

​
Queueable Listeners

For heavy processing, implement ShouldQueue to handle events asynchronously: 
namespace App\Listeners;

use Illuminate\Contracts\Queue\ShouldQueue;
use LarAgent\Events\ConversationEnded;

class LogConversationMetrics implements ShouldQueue
{
    public function handle(ConversationEnded $event): void
    {
        // This runs in the background
        $metrics = [
            'provider' => $event->agentDto->provider,
            'tools_used' => count($event->agentDto->tools),
            'response_length' => strlen($event->message?->getContent() ?? ''),
        ];
        
        Analytics::track('conversation_completed', $metrics);
    }
}