Stream voice AI agent debug events

AI Agentsvoice AI observability

Select a voice AI debug level, stream matching events to your webhook, and handle them as they arrive.

observability

The claim

enable_debug_events(level) writes debug_webhook_url and debug_webhook_level into the document’s params. The URL is the agent’s own /debug_events route, behind the same basic auth as the rest of the agent. The platform POSTs each event the level selects, and the function you register with on_debug_event receives every one with its label and full body.

Why it holds

The ai params reference documents both fields. debug_webhook_url receives “each interaction between the AI and end user”. debug_webhook_level is 0 to 2, and level 2 adds conversation_add, llm_request and llm_response.

How it works

class WatchedAgent(AgentBase):
    def __init__(self):
        super().__init__(name="watched", route="/watched")
        self.enable_debug_events(level=DEBUG_LEVEL)

@agent.on_debug_event
def watch(event_type, data):
    EVENTS.append((event_type, data.get("call_id")))
    if event_type == "llm_error":
        ERROR_EVENTS.append({"call_id": data.get("call_id"), "detail": data})

What the platform receives in the document:

{"params": {"debug_webhook_url": "https://user:pass@host/watched/debug_events/?__token=...",
            "debug_webhook_level": 1}}

The SDK’s route, _handle_debug_events_request in web_mixin.py, reads the event label from label and falls back to action. It logs the event as debug_event, then calls your handler with the label and the whole body, awaiting it if it is async. The enable_debug_events docstring in ai_config_mixin.py describes level 1 as barge, errors, session start and end, and step changes.

Limitations

The verifier posts events of the documented shape; it cannot generate the platform’s own. Which labels arrive at level 1 is the SDK’s description, not something proven here.

Level 2 posts every model request and response. Through a tunnel on one call that is fine; across a fleet, size your endpoint for it. Per the reference, setting debug_webhook_url turns the stream on, so lowering the level thins the stream rather than stopping it.

What to change first

Remove enable_debug_events from __init__ and run the verifier. The first assertion fails because params no longer carries the URL, and the platform has nowhere to send anything. The verifier already renders at levels 1 and 2 itself; to hear level 2 on a call, set DEBUG_LEVEL=2 in .env and run python app.py.

Where this sits

Before this

Give a voice AI agent a tool

Extract structured data after a call

python/app.py

"""Stream agent debug events.

`enable_debug_events()` puts `debug_webhook_url` and `debug_webhook_level`
into the document's `params`, pointed at the agent's own `/debug_events`
route. The platform POSTs each selected event there during the call, behind
the same basic auth as the rest of the agent. The handler you register with
`on_debug_event` receives every one as it lands.

The level selects the events. Per the SDK, level 1 carries barge, errors,
session start and end, and step changes; level 2 adds every LLM request and
response. Level 2 is a lot of traffic through a tunnel. Turn it on for one
failing call, not for a fleet.

Written against signalwire-sdk 3.0.1.
"""
import os

from dotenv import load_dotenv
from signalwire import AgentBase

# the SDK does not read .env for you
load_dotenv()

DEBUG_LEVEL = int(os.getenv("DEBUG_LEVEL", "1"))

# Every event the handler saw, oldest first: (event_type, call_id), and the
# llm_error events on their own. A real handler forwards these to your
# logging or paging.
EVENTS = []
ERROR_EVENTS = []


class WatchedAgent(AgentBase):
    def __init__(self):
        super().__init__(name="watched", route="/watched")
        self.prompt_add_section(
            "Role",
            "You take messages for a bicycle workshop. Ask for the caller's "
            "name and what they need, then say the workshop will call back.",
        )
        # writes params.debug_webhook_url and params.debug_webhook_level
        # into the rendered document
        self.enable_debug_events(level=DEBUG_LEVEL)


agent = WatchedAgent()


@agent.on_debug_event
def watch(event_type, data):
    """Called for every event the platform POSTs to /debug_events."""
    EVENTS.append((event_type, data.get("call_id")))
    if event_type == "llm_error":
        # the one event worth paging someone for
        ERROR_EVENTS.append({"call_id": data.get("call_id"), "detail": data})


if __name__ == "__main__":
    agent.serve(host="0.0.0.0", port=int(os.getenv("PORT", "3000")))

# Stream agent debug events, in plain SWML: two params on the ai verb turn the
# stream on. The platform POSTs each event to debug_webhook_url as it happens.
# debug_webhook_level selects them: 1 for barge, errors, session start and end
# and step changes; 2 adds every LLM request and response. Credentials in the
# URL protect the endpoint.
version: "1.0.0"
sections:
  main:
    - ai:
        prompt:
          text: >
            You take messages for a bicycle workshop. Ask for the caller's
            name and what they need, then say the workshop will call back.
        params:
          debug_webhook_url: "https://user:password@your-host.example/debug_events"
          debug_webhook_level: 1

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # set SWML_BASIC_AUTH_PASSWORD
python app.py

The webhook needs a public HTTPS URL. For a local run, expose port 3000 with a tunnel such as ngrok and use that hostname. Point a number’s SWML webhook at https://<user>:<password>@<your-host>/watched/, call, and interrupt the agent mid-sentence. The debug_event log line names the event.

Verify it

No network, no account. The verifier drives the agent’s own HTTP app with FastAPI’s test client and POSTs events in the documented shape.

python verify.py          # from the recipe folder, not python/

It renders and validates the SWML, then asserts the following.

params.debug_webhook_url points at this agent’s /debug_events route and debug_webhook_level is 1
with DEBUG_LEVEL=2 the document says 2
the route refuses a POST without basic auth and does not call the handler
the route refuses a GET with 405
a barge POST returns {"status": "ok"} and the handler receives ("barge", call_id)
an llm_error POST reaches the handler, which records the body on its own list
a body with action but no label reaches the handler under the action name
the plain-SWML surface validates with the same two params

Report an issue