Skip to main content
Agent events track the main lifecycle stages of an agent conversation, from initialization through tool execution to termination.
This page documents Laravel events that LarAgent dispatches. For in-class hooks that can modify agent behavior, see Agent Hooks.

Lifecycle Events

AgentInitialized

Dispatched when the agent completes its initialization process and is ready to handle conversations.
LarAgent\Events\AgentInitialized
agentDto
AgentDTO
required
Complete agent configuration including provider, tools, instructions, and response schema.
public function handle(AgentInitialized $event): void
{
    $provider = $event->agentDto->provider;
    $tools = $event->agentDto->tools;
}

ConversationStarted

Dispatched when the respond() method begins execution, marking the start of a new conversation turn.
LarAgent\Events\ConversationStarted
agentDto
AgentDTO
required
Current agent configuration at the start of the conversation.
public function handle(ConversationStarted $event): void
{
    $message = $event->agentDto->message;
    // Log conversation start, initialize metrics, etc.
}

ConversationEnded

Dispatched when the respond() method completes execution.
LarAgent\Events\ConversationEnded
agentDto
AgentDTO
required
Final agent configuration at the end of the conversation.
message
MessageInterface|array|null
required
The final response message or null if no response was generated.
Message instance includes the token usage data. Use toArrayWithMeta to get it as an array.
public function handle(ConversationEnded $event): void
{
    $response = $event->message;
    // Log conversation end, calculate metrics, cleanup
}

ToolChanged

Dispatched when tools are dynamically added to or removed from the agent during runtime.
LarAgent\Events\ToolChanged
agentDto
AgentDTO
required
Current agent configuration.
tool
ToolInterface
required
The tool instance that was added or removed.
added
boolean
required
true if the tool was added, false if it was removed.
public function handle(ToolChanged $event): void
{
    $toolName = $event->tool->getName();
    $action = $event->added ? 'added' : 'removed';
}

AgentCleared

Dispatched when the agent’s state is cleared, typically resetting conversation history and context.
LarAgent\Events\AgentCleared
agentDto
AgentDTO
required
Agent configuration at the time of clearing.

EngineError

Dispatched when an error occurs in the LLM engine during processing.
LarAgent\Events\EngineError
agentDto
AgentDTO
required
Agent configuration when the error occurred.
exception
Throwable
required
The exception that was thrown by the LLM engine.
public function handle(EngineError $event): void
{
    $error = $event->exception->getMessage();
    $provider = $event->agentDto->provider;
    // Log error, send alerts, implement fallback logic
}

Hook Events

These events provide hooks before and after critical operations.

BeforeReinjectingInstructions

Dispatched before instructions are reinjected into the conversation history.
LarAgent\Events\BeforeReinjectingInstructions
agentDto
AgentDTO
required
Current agent configuration.
chatHistory
ChatHistoryInterface
required
The chat history interface before instruction reinjection.

BeforeSend / AfterSend

Dispatched before and after adding a message to chat history.
LarAgent\Events\BeforeSend
LarAgent\Events\AfterSend
agentDto
AgentDTO
required
Current agent configuration.
history
ChatHistoryInterface
required
The conversation history.
message
MessageInterface|null
required
The message being sent.

BeforeResponse / AfterResponse

Dispatched before sending to and after receiving from the LLM.
LarAgent\Events\BeforeResponse
LarAgent\Events\AfterResponse
agentDto
AgentDTO
required
Current agent configuration.
message
MessageInterface|null
required
The message (user message for Before, LLM response for After).

BeforeToolExecution / AfterToolExecution

Dispatched before and after a tool is executed.
LarAgent\Events\BeforeToolExecution
LarAgent\Events\AfterToolExecution
agentDto
AgentDTO
required
Current agent configuration.
tool
ToolInterface
required
The tool instance being executed.
toolCall
ToolCallInterface
required
The tool call with getId, getToolName, and getArguments methods.
result
mixed
(AfterToolExecution only) The result returned by the tool.

BeforeSaveHistory

Dispatched before persisting the conversation history to storage.
LarAgent\Events\BeforeSaveHistory
agentDto
AgentDTO
required
Current agent configuration.
history
ChatHistoryInterface
required
The conversation history about to be saved.

BeforeStructuredOutput

Dispatched before processing structured output from the LLM response.
LarAgent\Events\BeforeStructuredOutput
agentDto
AgentDTO
required
Current agent configuration including the response schema.
response
array
required
The raw structured response array before processing.