1. Invoking an Agent
Agents can be invoked via inference endpoints:-
Chat Mode
-
Streaming Mode
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
{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.
4. Event Payload Structure
All events are delivered as JSON objects.A sample event payload looks like this:
5. Event Fields Explained
Field | Type | Description |
---|---|---|
feature | string | Feature/component generating the event (e.g., llm_generation ). |
level | string | Logging level (DEBUG , INFO , ERROR ). |
status | string | Process status (in_progress , completed , failed ). |
message | string | Additional human-readable details. |
timestamp | string | ISO 8601 timestamp of event. |
event_type | string | Event type (e.g., llm_generation , thinking , processing ). |
run_id | string | Unique identifier for this agent run. |
trace_id | string | Trace identifier for distributed tracking. |
session_id | string | Identifier linking the event to the agent session. |
model | string | LLM model used (e.g., gpt-4o-mini ). |
provider | string | Model provider (e.g., openai ). |
log_id | string | Unique ID for this log entry. |
6. Example Event Sequence
A typical sequence of events during invocation:- Start – Agent invoked.
- Thinking Event – Intermediate reasoning steps. (Manager agents only)
- Processing Event – Status updates such as memory usage, KB retrieval, tool invocation.
- LLM Generation Completed – Final response generated (status:
completed
). - 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 validsession_id
, developers can monitor agent reasoning, processing states, completions, and errors—allowing for better debugging, logging, and user experience.