Event Setup Guide - Official LarAgent Documentation

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

Create a listener

php artisan make:listener AgentListener

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);
    }
}

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:

Feature	Agent Hooks	Laravel Events
Definition	Override methods in agent class	Separate listener classes
Scope	Single agent class	Application-wide
Async support	No	Yes (via queues)
Modify behavior	Can return `false` to halt	Observe only
Use case	Agent-specific logic	Cross-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);
    }
}

​Quickstart

​AgentDTO Structure

​Available Events

Agent Events

Context Events

History Events

​Events vs Agent Hooks

​Queueable Listeners

Quickstart

AgentDTO Structure

Available Events

Events vs Agent Hooks

Queueable Listeners