Event Overview

All events are in the Vizra\VizraADK\Events namespace and use Laravel's event system.

use Vizra\VizraADK\Events\AgentExecutionStarting;
use Illuminate\Support\Facades\Event;

// Listen to an event
Event::listen(AgentExecutionStarting::class, function (AgentExecutionStarting $event) {
    Log::info('Agent starting', [
        'agent' => $event->agentName,
        'input' => $event->input
    ]);
});

Agent Execution Events

AgentExecutionStarting

Fired when an agent begins execution.

class AgentExecutionStarting
{
    public function __construct(
        public AgentContext $context,
        public string $agentName,
        public mixed $input
    ) {}
}

AgentExecutionFinished

Fired when an agent completes execution.

class AgentExecutionFinished
{
    public function __construct(
        public AgentContext $context,
        public string $agentName
    ) {}
}

AgentResponseGenerated

Fired when an agent generates its final response.

class AgentResponseGenerated
{
    public function __construct(
        public AgentContext $context,
        public string $agentName,
        public mixed $finalResponse
    ) {}
}

LLM Interaction Events

LlmCallInitiating

Fired before making a call to the LLM.

class LlmCallInitiating
{
    public function __construct(
        public AgentContext $context,
        public string $agentName,
        public array $promptMessages
    ) {}
}

LlmResponseReceived

Fired after receiving a response from the LLM.

class LlmResponseReceived
{
    public function __construct(
        public AgentContext $context,
        public string $agentName,
        public mixed $llmResponse
    ) {}
}

Tool Execution Events

ToolCallInitiating

Fired before executing a tool.

class ToolCallInitiating
{
    public function __construct(
        public AgentContext $context,
        public string $agentName,
        public string $toolName,
        public array $arguments
    ) {}
}

ToolCallCompleted

Fired after a tool completes execution.

class ToolCallCompleted
{
    public function __construct(
        public AgentContext $context,
        public string $agentName,
        public string $toolName,
        public string $result // JSON string
    ) {}
}

State Management Events

StateUpdated

Fired when agent state is updated.

class StateUpdated
{
    public function __construct(
        public AgentContext $context,
        public string $key,
        public mixed $value
    ) {}
}

MemoryUpdated

Fired when agent memory is updated.

class MemoryUpdated
{
    public function __construct(
        public AgentMemory $memory,
        public ?AgentSession $session,
        public string $updateType
    ) {}
}

Multi-Agent Events

TaskDelegated

Fired when an agent delegates a task to a sub-agent.

class TaskDelegated
{
    public function __construct(
        public AgentContext $parentContext,
        public AgentContext $subAgentContext,
        public string $parentAgentName,
        public string $subAgentName,
        public string $taskInput,
        public string $contextSummary,
        public int $delegationDepth
    ) {}
}

Usage Examples

Monitoring Agent Performance

use Vizra\VizraADK\Events\{AgentExecutionStarting, AgentExecutionFinished};
use Illuminate\Support\Facades\Event;

class AgentPerformanceMonitor
{
    private array $startTimes = [];

    public function register(): void
    {
        Event::listen(AgentExecutionStarting::class, [$this, 'handleStart']);
        Event::listen(AgentExecutionFinished::class, [$this, 'handleFinish']);
    }

    public function handleStart(AgentExecutionStarting $event): void
    {
        $this->startTimes[$event->context->getSessionId()] = microtime(true);
    }

    public function handleFinish(AgentExecutionFinished $event): void
    {
        $sessionId = $event->context->getSessionId();
        $duration = microtime(true) - $this->startTimes[$sessionId];

        Log::info('Agent execution completed', [
            'agent' => $event->agentName,
            'duration' => round($duration, 2) . 's'
        ]);
    }
}

Debugging Tool Calls

Event::listen(ToolCallInitiating::class, function (ToolCallInitiating $event) {
    Log::debug('Tool call starting', [
        'tool' => $event->toolName,
        'arguments' => $event->arguments,
        'session' => $event->context->getSessionId()
    ]);
});

Event::listen(ToolCallCompleted::class, function (ToolCallCompleted $event) {
    $result = json_decode($event->result, true);
    Log::debug('Tool call completed', [
        'tool' => $event->toolName,
        'success' => $result['success'] ?? false
    ]);
});

Memory Tracking

Event::listen(MemoryUpdated::class, function (MemoryUpdated $event) {
    switch ($event->updateType) {
        case 'learning_added':
            Log::info('New learning stored', [
                'agent' => $event->memory->agent_name,
                'learning' => $event->memory->learnings->last()
            ]);
            break;

        case 'fact_added':
            Log::info('New fact stored', [
                'agent' => $event->memory->agent_name,
                'fact' => $event->memory->facts->last()
            ]);
            break;
    }
});