AgentOS markAgentOS

Diagnostics and Replay


Diagnostics and replay help explain what happened during an AgentOS turn. Use them when a result was surprising, slow, expensive, interrupted, or hard to reproduce from the chat transcript alone.

Diagnostics

Diagnostics are runtime logging controls exposed through the gateway.

Check status:

agentos diagnostics status
agentos diagnostics status --json

Enable diagnostics:

agentos diagnostics on

Enable raw turn-call capture when a maintainer asks for deeper provider request evidence:

agentos diagnostics on --raw

Turn diagnostics off after collecting enough evidence:

agentos diagnostics off

When to Use Diagnostics

Use diagnostics for:

  • provider retries, timeouts, or empty responses;
  • Pilot Router model decisions;
  • prompt-cache or cache-break investigation;
  • compaction lifecycle events;
  • large tool-result compression;
  • channel delivery failures;
  • unusually high cost or latency.

Avoid leaving raw diagnostics on longer than needed. Raw captures may contain private prompts, tool outputs, local paths, or provider-visible content.

Replay a Recorded Turn

Replay reads a recorded turn from the decision log and prints a human-readable transcript. It is read-only: it does not re-run tools.

agentos replay --session <session-key> --turn <turn-id>

Use replay when:

  • a chat has moved on but you need to inspect an earlier turn;
  • a bug report needs concise reproduction evidence;
  • you want to compare transcript output with diagnostics and cost data.

Where a Turn's Time Goes

Every turn records a wall-clock breakdown. The gateway log gets one turn.timing line per turn, and the decision log row carries the same data under timing (schema 16), which agentos replay prints:

  • total_ms: the whole turn; pre_provider_ms: turn start to the first provider request; first_text_ms: turn start to the first streamed text.
  • provider_ms, tool_ms, approval_wait_ms (time with at least one approval outstanding), finalize_ms, and iterations (provider calls).
  • per stage (input, provider_and_tools, prompt_assembler, agent_bootstrap, compaction_and_history, attachment, stream_consumer, turn_finalizer; in the log line as stage_<name>_ms);
  • per provider call: start offset, then time to first event, first text and end of stream, with input/output tokens; per tool batch: duration, number of calls and approval wait.
  • retries: model calls the engine repeated, by category (in the log line as retry_<category>). text_tool_call counts replies that wrote a tool call out as text instead of calling the tool; the engine drops such a reply and asks once more, and the turn-call log records it as a turn_policy_decision with action: retry_text_tool_call.

Rows written before schema 16 have no timing; replay shows only the total latency for them.

Pair Replay With Sessions

Find the session first:

agentos sessions list
agentos sessions show <session-key>

Export the full session if exact context matters:

agentos sessions export <session-key> --output session.md

Safe Sharing

Before sharing diagnostics, replay output, or exported sessions publicly, remove:

  • provider keys and bearer tokens;
  • private local paths;
  • private channel identifiers;
  • customer, project, or account names that should not be public;
  • raw provider prompts or tool outputs that include confidential content.

Read next: