Skip to main content

​
Event Overview

All class-based 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

Fired when an agent begins execution.
class AgentExecutionStarting
{
    public function __construct(
        public AgentContext $context,
        public string $agentName,
        public mixed $input
    ) {}
}
Properties:
PropertyDescription
$contextThe agent execution context
$agentNameName of the agent being executed
$inputInitial input provided to the agent
Fired when an agent completes execution.
class AgentExecutionFinished
{
    public function __construct(
        public AgentContext $context,
        public string $agentName
    ) {}
}
Properties:
PropertyDescription
$contextThe agent execution context
$agentNameName of the agent that finished
Fired when an agent generates its final response.
class AgentResponseGenerated
{
    public function __construct(
        public AgentContext $context,
        public string $agentName,
        public mixed $finalResponse
    ) {}
}
Properties:
PropertyDescription
$contextThe agent execution context
$agentNameName of the agent
$finalResponseThe final response generated by the agent

​
LLM Interaction Events

Fired before making a call to the LLM.
class LlmCallInitiating
{
    public function __construct(
        public AgentContext $context,
        public string $agentName,
        public array $promptMessages
    ) {}
}
Properties:
PropertyDescription
$contextThe agent execution context
$agentNameName of the agent making the call
$promptMessagesArray of messages being sent to the LLM
Fired after receiving a response from the LLM.
class LlmResponseReceived
{
    public function __construct(
        public AgentContext $context,
        public string $agentName,
        public mixed $llmResponse,
        public ?PendingRequest $request = null
    ) {}
}
Properties:
PropertyDescription
$contextThe agent execution context
$agentNameName of the agent
$llmResponseThe response from the LLM
$requestThe Prism request object (optional)
Fired when an LLM API call fails.
class LlmCallFailed
{
    public function __construct(
        public AgentContext $context,
        public string $agentName,
        public Throwable $exception,
        public ?PendingRequest $request = null
    ) {}
}
Properties:
PropertyDescription
$contextThe agent execution context
$agentNameName of the agent
$exceptionThe exception that caused the failure
$requestThe failed request details (optional)

​
Tool Execution Events

Fired before executing a tool.
class ToolCallInitiating
{
    public function __construct(
        public AgentContext $context,
        public string $agentName,
        public string $toolName,
        public array $arguments
    ) {}
}
Properties:
PropertyDescription
$contextThe agent execution context
$agentNameName of the agent executing the tool
$toolNameName of the tool being called
$argumentsArguments passed to the tool
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
    ) {}
}
Properties:
PropertyDescription
$contextThe agent execution context
$agentNameName of the agent
$toolNameName of the tool that completed
$resultJSON-encoded result from the tool
Fired when a tool call encounters an error.
class ToolCallFailed
{
    public function __construct(
        public AgentContext $context,
        public string $agentName,
        public string $toolName,
        public Throwable $exception
    ) {}
}
Properties:
PropertyDescription
$contextThe agent execution context
$agentNameName of the agent
$toolNameName of the tool that failed
$exceptionThe exception that caused the failure

​
State Management Events

Fired when agent state is updated.
class StateUpdated
{
    public function __construct(
        public AgentContext $context,
        public string $key,
        public mixed $value
    ) {}
}
Properties:
PropertyDescription
$contextThe agent execution context
$keyThe state key that was updated
$valueThe new value
Fired when agent memory is updated.
class MemoryUpdated
{
    public function __construct(
        public AgentMemory $memory,
        public ?AgentSession $session,
        public string $updateType
    ) {}
}
Properties:
PropertyDescription
$memoryThe agent memory instance
$sessionThe associated session (optional)
$updateTypeType of update performed
Update Types:
TypeDescription
'session_completed'Session summary extracted
'learning_added'New learning stored
'fact_added'New fact stored

​
Multi-Agent Events

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
    ) {}
}
Properties:
PropertyDescription
$parentContextContext of the delegating agent
$subAgentContextContext for the sub-agent
$parentAgentNameName of the parent agent
$subAgentNameName of the sub-agent receiving the task
$taskInputThe task being delegated
$contextSummarySummary of context passed to sub-agent
$delegationDepthCurrent depth of delegation chain

​
Media Generation Events

These are string-based events fired by MediaGenerationJob when processing queued media generation tasks (images, audio, etc.). 
use Illuminate\Support\Facades\Event;

// Listen to media events
Event::listen('media.job.completed', function (array $payload) {
    Log::info('Media job completed', [
        'job_id' => $payload['job_id'],
        'agent' => $payload['agent_class'],
    ]);
});
Fired when any media generation job completes successfully.
event('media.job.completed', [
    'job_id' => $jobId,
    'agent_class' => $agentClass,
    'response' => $response,  // ImageResponse or AudioResponse
]);
Payload:
KeyTypeDescription
job_idstringUnique identifier for the job
agent_classstringFully qualified class name of the media agent
responseImageResponse|AudioResponseThe generated media response object
Example:
Event::listen('media.job.completed', function (array $payload) {
    $url = $payload['response']->url();

    // Notify user that their image is ready
    Notification::send($user, new MediaReadyNotification($url));
});
Fired when a specific agent’s media job completes. The event name includes the agent’s name (e.g., media.image_agent.completed).
event("media.{$agentName}.completed", [
    'job_id' => $jobId,
    'response' => $response,
    'session_id' => $sessionId,
]);
Payload:
KeyTypeDescription
job_idstringUnique identifier for the job
responseImageResponse|AudioResponseThe generated media response object
session_idstringSession ID associated with the job
Example:
// Listen specifically for image agent completions
Event::listen('media.image_agent.completed', function (array $payload) {
    $sessionId = $payload['session_id'];
    $imageUrl = $payload['response']->url();

    // Update the session with the generated image
    broadcast(new ImageGeneratedEvent($sessionId, $imageUrl));
});

// Listen for audio agent completions
Event::listen('media.audio_agent.completed', function (array $payload) {
    // Handle audio-specific logic
});
Fired when a media generation job fails after all retry attempts.
event('media.job.failed', [
    'job_id' => $jobId,
    'agent_class' => $agentClass,
    'error' => $exception->getMessage(),
]);
Payload:
KeyTypeDescription
job_idstringUnique identifier for the failed job
agent_classstringFully qualified class name of the media agent
errorstringError message describing the failure
Example:
Event::listen('media.job.failed', function (array $payload) {
    Log::error('Media generation failed', [
        'job_id' => $payload['job_id'],
        'agent' => $payload['agent_class'],
        'error' => $payload['error'],
    ]);

    // Notify user of failure
    Notification::send($user, new MediaFailedNotification($payload['error']));
});

​
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;
    }
});
Event Best Practices:
  • Use event listeners for cross-cutting concerns like logging and monitoring
  • Keep event handlers lightweight to avoid impacting agent performance
  • Use queued listeners for heavy processing tasks
  • Events are synchronous by default - be mindful of execution time
  • All class-based events include the AgentContext for accessing session state
  • Tool results are JSON strings - decode them for processing
  • Media events are string-based and receive array payloads

​
Next Steps

Agent Lifecycle

Learn about the agent execution flow

API Reference

View all API references