Skip to main content
This document 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 
    POST https://agent-prod.studio.lyzr.ai/v3/inference/chat
  • Streaming Mode 
    POST https://agent-prod.studio.lyzr.ai/v3/inference/stream
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 
    wss://metrics.studio.lyzr.ai/session/{session_id}
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: 
{
  "feature": "llm_generation",
  "level": "DEBUG",
  "status": "in_progress",
  "message": "",
  "timestamp": "2025-09-29T05:56:39.858406+00:00",
  "event_type": "llm_generation",
  "run_id": "0ecb09b6-77d7-4709-a7ce-a43d3f5d748c",
  "trace_id": "7833aae5-13df-47e6-a1d4-35f3e74d1799",
  "session_id": "68d0bbdef8c41f367a3f3a11-6fwxvvb1xxr",
  "model": "gpt-4o-mini",
  "provider": "openai",
  "log_id": "311d863d-c680-476f-b563-94cdb00d487b"
}

​
5. Event Fields Explained

FieldTypeDescription
featurestringFeature/component generating the event (e.g., llm_generation).
levelstringLogging level (DEBUG, INFO, ERROR).
statusstringProcess status (in_progress, completed, failed).
messagestringAdditional human-readable details.
timestampstringISO 8601 timestamp of event.
event_typestringEvent type (e.g., llm_generation, thinking, processing).
run_idstringUnique identifier for this agent run.
trace_idstringTrace identifier for distributed tracking.
session_idstringIdentifier linking the event to the agent session.
modelstringLLM model used (e.g., gpt-4o-mini).
providerstringModel provider (e.g., openai).
log_idstringUnique ID for this log entry.

​
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.
⌘I