***

title: on_debug_event
slug: /reference/python/agents/agent-base/on-debug-event
description: Register a callback for debug events received at the /debug_events endpoint.
max-toc-depth: 3
---------------------

For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

[enable-debug-events]: /docs/server-sdks/reference/python/agents/agent-base/enable-debug-events

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

<Note>
  [`enable_debug_events()`][enable-debug-events] must be called before events will be delivered.
</Note>

## **Parameters**

<ParamField path="handler" type="Callable[[str, dict], None]" required={true} toc={true}>
  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
</ParamField>

## **Returns**

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

## **Example**

```python {7}
from signalwire import AgentBase

agent = AgentBase(name="debug-agent", route="/debug")
agent.set_prompt_text("You are a helpful assistant.")
agent.enable_debug_events(level=1)

@agent.on_debug_event
def handle_debug(event_type, data):
    if event_type == "llm_error":
        print(f"LLM error: {data}")
    elif event_type == "barge":
        print(f"Barge detected: {data.get('barge_elapsed_ms')}ms")
    elif event_type == "step_change":
        print(f"Step changed to: {data.get('step')}")

agent.serve()
```