on_debug_event | SignalWire

Register a callback for debug events received at the /debug_events endpoint. Use as a decorator. Both sync and async handlers are supported.

enable_debug_events() must be called before events will be delivered.

Parameters

handler

Callable[[str, dict], None]Required

Callback function with signature (event_type: str, data: dict).

event_type — Event label string (e.g., "barge", "llm_error", "session_start", "step_change")
data — Full event payload including call_id, label, and event-specific fields

Returns

Callable — The handler function, unchanged. This allows on_debug_event to be used as a decorator.

Example

1 from signalwire import AgentBase
2 
3 agent = AgentBase(name="debug-agent", route="/debug")
4 agent.set_prompt_text("You are a helpful assistant.")
5 agent.enable_debug_events(level=1)
6 
7 @agent.on_debug_event
8 def handle_debug(event_type, data):
9     if event_type == "llm_error":
10         print(f"LLM error: {data}")
11     elif event_type == "barge":
12         print(f"Barge detected: {data.get('barge_elapsed_ms')}ms")
13     elif event_type == "step_change":
14         print(f"Step changed to: {data.get('step')}")
15 
16 agent.serve()