Skip to main content

Debugging AI Requests

Governed Chat Completions and Responses requests can produce delivered Event evidence when the gateway is connected to the control plane and event delivery is available. History adds retained context only when capture is configured. Use the CLI for live signals and the Events API for delivered request outcomes. Use the console for capture-enabled session context, audit chronology, and review work.

Evidence is not guaranteed for every request. History can be disabled, its delivery is fire-and-forget, a standalone gateway may have no control-plane sink, and Messages or WebSocket traffic does not have the same policy-evidence path as Chat Completions and Responses. Treat a missing record as a signal to check capture, connectivity, and request-family support—not as proof that the request never occurred.

Before you begin​

  • Select an authenticated CLI profile for the affected region, or provide a control-plane token with events:read. An application request token is not a substitute.
  • Preserve the client response, UTC time window, request ID, gateway or agent, model, and environment when available.
  • Confirm the application used the expected gateway and a documented request family.
  • Use History, Trail, and Inbox only when the record exists and your role can read the owning surface.

Choose the right surface​

NeedBest surface
Live runtime feed while reproducing an issuekt events tail
One request's delivered runtime outcomekt events tail or GET /v1/events with required since
Retained prompt, response, or session contextHistory, only when capture is enabled
Audit chronology or exportable evidenceTrail
Human-review items created by the requestInbox
Runtime inventory and healthGateways

Start with the CLI when reproducing a live issue​

Basic live feed:

kt events tail --follow

Recent decision events as JSON:

kt events tail --since 10m --event-type decision --limit 20 --json

Only blocked decisions:

kt events tail --follow --event-type decision --verdict blocked

Limit investigation to one gateway:

kt events tail --since 30m --gateway-id gw_123 --json

Use the CLI when you are actively reproducing a problem and need immediate confirmation that the gateway is seeing traffic.

Add History only when captured detail is available​

After you identify the request Event, use History only when capture is enabled and retained context is needed to answer questions such as:

  • What prompt, response, or session context was retained?
  • How does the captured session compare with nearby captured requests?
  • Did retained content change after a rollout?

Use the Event and request ID for the outcome, policy evidence, configuration version, provider, and model. An absent History record is not evidence that the request did not occur.

Use Trail when the issue needs chronology or export​

Use Trail when you need:

  • An audit-oriented chronology of related actions.
  • Exportable evidence for incident response or compliance review.
  • Proof of follow-up activity after the original request.

Use Inbox when the request triggered human review​

If the request produced an escalation or approval task, open Inbox and inspect the linked review item there. Resolve the review item only after you understand the underlying request context.

Common debugging patterns​

A request is blocked unexpectedly​

  1. Reproduce the issue while kt events tail --follow --event-type decision --verdict blocked is running.
  2. Match the request ID and review the Event's policy results and configuration version.
  3. If capture is enabled and retained session context is necessary, open the matching request in History.
  4. Compare with the last rollout in Configurations.

A request is slower than expected​

  1. Confirm the problem is current with kt events tail --since 10m --limit 20 --json.
  2. Check gateway and provider health from the runtime diagnostics.
  3. Open Gateways to confirm the expected runtime is healthy.
  4. Compare nearby Events and runtime metrics to determine whether the slowdown is isolated or systemic. Add captured History context only when capture is enabled and the investigation needs it.

A request triggered human review​

  1. Open the related Inbox item and retain its request ID.
  2. Query the matching Event with kt events tail --since <window> --json or GET /v1/events?since=<window>.
  3. Add History only when capture is enabled and the retained session context is necessary.
  4. Resolve the review item only after you understand the request and rollout context.

Best practices​

PracticeWhy
Use kt events tail --follow during reproductionConfirms the runtime is receiving the traffic you think it is
Narrow by --verdict, --event-type, or --gateway-idKeeps the live feed readable
Compare request Events before and after rolloutDistinguishes config regressions from isolated incidents
Treat History as capture-dependent contextAvoids interpreting an absent session as proof that no request occurred
Use Trail for evidence handoffKeeps audit exports tied to customer-facing workflows

Next steps​