Skip to content

AI observability guide: post_prompt_url and debug_webhook_url are undiscoverable #519

Description

@briankwest

Problem

Both of the AI agent's observability surfaces exist but are effectively undiscoverable from a debugging mindset:

  • post_prompt_url is documented only as a configuration property on the ai method reference — nowhere near any discussion of logging, debugging, or observability. Its payload (conversation log, per-function SWAIG call log with arguments and results, call timeline including error entries, timings, summary) is exactly what a developer debugging an agent needs, and nothing connects the two.
  • ai.params.debug_webhook_url — a real-time per-event stream (each SWAIG request/response exchange, voice errors, text normalization, post-prompt delivery) — is not documented near any debugging discussion either.

A developer evaluating the platform concluded "a developer debugging a SWML agent has essentially no server-side telemetry" — wrong, but a reasonable reading of the docs as organized.

Fix

  1. An observability/debugging guide under the AI section leading with both features.
  2. Reference documentation for the post_prompt payload fields (call_log, raw_call_log, call_timeline, swaig_log, global_data, post_prompt_data, timestamps, accounting totals).
  3. Document debug_webhook_url / debug_webhook_level and the event envelope (call_info + per-event payload).
  4. Cross-link from the ai reference pages.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions