Skip to main content
This explains how Lyzr Agents emit runtime events when invoked through the Lyzr Platform. These events provide real-time insights into agent execution, including reasoning steps, model responses, and lifecycle updates.

​
1. Invoking an Agent

Agents can be invoked via inference endpoints:
  • Chat Mode
  • Streaming Mode
When an agent is invoked, a unique session_id is generated and associated with the request.
This ID is critical for subscribing to real-time agent events.

​
2. Receiving Agent Events

Agent runtime events are delivered through a WebSocket connection.
  • WebSocket Endpoint
Replace {session_id} with the same ID returned during agent invocation. ⚠️ Note:
  • Using an incorrect or expired session_id will result in no events being streamed.
  • Ensure the WebSocket client stays open for the duration of the session.

​
3. Event Lifecycle

During execution, multiple events are emitted to describe the agent’s state. These typically include:
  • Thinking Events – Intermediate reasoning steps of the agent. (Manager agents only)
  • Processing Events – Structured progress updates from the LLM and orchestrator.
  • Completion Events – Indicate successful completion of response generation.
  • Error Events – Capture failures or issues during inference and integrations.
Events can be consumed in real-time to monitor, log, or debug agent behavior.

​
4. Event Payload Structure

All events are delivered as JSON objects.
A sample event payload looks like this:

​
5. Event Fields Explained

​
6. Example Event Sequence

A typical sequence of events during invocation:
  1. Start – Agent invoked.
  2. Thinking Event – Intermediate reasoning steps. (Manager agents only)
  3. Processing Event – Status updates such as memory usage, KB retrieval, tool invocation.
  4. LLM Generation Completed – Final response generated (status: completed).
  5. Final Response Delivered – Output returned to the caller.

​
7. Best Practices

  • Always reuse the same session_id for invocation and WebSocket subscription.
  • Handle ERROR level events gracefully to avoid breaking downstream applications.
  • Use events for:
    • ✅ Real-time monitoring
    • ✅ Debugging agent behavior
    • ✅ Providing user-facing progress updates
  • Maintain persistent connections for long-running agents.

​
✅ Summary

The Agent Events API in Lyzr enables real-time observability into agent execution. By subscribing to the WebSocket channel with a valid session_id, developers can monitor agent reasoning, processing states, completions, and errors—allowing for better debugging, logging, and user experience.