Monitor agent status, errors, and performance

This page helps you choose the right path for common monitoring goals, then links you to the detailed setup guides.

Runtime event handling on client apps usually serves one of the following goals:

Update the app UI according to the agent's current state
Capture errors and debug logs during a live session
Collect lifecycle and latency data on your server

Choose a path for each goal

Goal	Best path	Use these events
Update the in-call UI with the agent's current state	Toolkit callbacks in the client	`onAgentStateChanged`, `onAgentListeningChanged`, `onAgentThinkingChanged`, `onAgentSpeakingChanged`
Handle interruptions during a live session	Toolkit callbacks in the client	`onAgentInterrupted`
Show immediate failures in the app	Toolkit callbacks in the client	`onAgentError`, `onDebugLog` (Android), `DEBUG_LOG` (Web)
Alert on agent failures from your backend	Webhooks	`110 agent error`, `102 agent left`
Monitor latency and runtime health	Toolkit for live UX, webhooks for aggregation	`onAgentMetrics`, `111 agent metrics`
Track when sessions start and stop	Webhooks	`101 agent joined`, `102 agent left`
Retrieve conversation history and turn data after a session	Webhooks or REST API	`103 agent history`, `112 turns finished`, `history`, `turns`

Use client callbacks for live state and local debugging

Use the toolkit when the event must arrive during the current session:

onAgentStateChanged is the main UI state callback for silent, listening, thinking, and speaking.
onAgentListeningChanged, onAgentThinkingChanged, and onAgentSpeakingChanged are better when you need separate loading, waveform, or avatar behaviors.
onAgentInterrupted is useful for turn-level UX, for example when you need to stop playback or show that a user barged in.
onAgentError is the primary callback for module failures such as LLM or TTS errors.
onDebugLog on Android and DEBUG_LOG on Web are useful when you want extra client-side diagnostics while reproducing issues.

To receive these events, start the agent with RTM enabled and subscribe to channel messages before the session starts:

{
  "advanced_features": {
    "enable_rtm": true
  },
  "properties": {
    "channel": "voice-demo"
  },
  "parameters": {
    "data_channel": "rtm",
    "enable_metrics": true,
    "enable_error_message": true
  }
}

For the first-step setup of both client and server paths, see Get runtime events. For the full client integration flow, see Client-side events.

Use webhooks for durable monitoring and alerting

Use webhook events when the data must leave the device and be available for dashboards, alerts, and post-session analysis:

101 agent joined confirms that the agent started successfully.
102 agent left tells you how the session ended, including failed or idle-timeout exits.
103 agent history and 112 turns finished deliver post-session records for history, archiving, and turn analytics.
104 agent expire warns your backend that the agent's RTC token is about to expire.
110 agent error captures structured module errors with vendor-specific codes and messages.
111 agent metrics reports latency and other runtime metrics that are better suited to backend aggregation.

If you need to answer questions such as why a session failed, which customers are seeing LLM errors, or how long TTS takes in production, webhook events are the better primary source.

For the first-step setup of both client and server paths, see Get runtime events. For the full server integration flow, setup steps, request headers, request body, and signature verification, see Webhooks. For complete webhook payloads, see Notification event types.

Choose the right path for shared goals

Some runtime goals are available through both client and server paths. Use the tabs below to choose the implementation that matches your use case.

Errors

Use client events when you need to react during the current session:

onAgentError for immediate module failures such as LLM or TTS errors
onDebugLog on Android and DEBUG_LOG on Web for local diagnostics during reproduction
UI updates, retries, graceful degradation, and session-local logging

This path is best when the user is still in the call and the app needs to respond immediately.

Use webhook events when you need durable backend observability:

110 agent error for structured module failures
102 agent left to understand whether the session terminated abnormally
Alerting, dashboards, incident review, and cross-session aggregation

This path is best when the problem must be visible outside the current device or session.

Performance

Use onAgentMetrics when performance must shape the live experience:

Show current latency or quality indicators in the UI
React to degraded experience during the session
Compare what the user feels with what the client observes

Use 111 agent metrics when performance must be monitored over time:

Store metrics for dashboards and alerts
Compare cohorts by labels
Analyze regression patterns across sessions and environments

Recommended monitoring pattern

For most production apps, use both channels together:

Use toolkit callbacks to update the local UI and react during the live session.
Use webhooks to store durable records for alerts, analytics, and debugging.
Correlate both streams with shared fields such as agent_id, name, channel, turn_id, and labels.

labels are especially useful when you want to group runtime data by customer segment, campaign, environment, or experiment.