Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Debug a Run

Use this when a run stops unexpectedly or tool behavior is incorrect.

Prerequisites

  • Target thread_id and (if available) run_id.
  • Access to the emitted event stream and persisted thread data.

Steps

  1. Confirm termination reason from AgentEvent::RunFinish { termination, .. }.

termination is authoritative and usually one of:

  • NaturalEnd
  • BehaviorRequested
  • Stopped(...)
  • Cancelled
  • Suspended
  • Error
  1. Inspect event timeline ordering:
  • StepStart / StepEnd
  • ToolCallStart / ToolCallDone
  • InferenceComplete
  • Error
  1. Verify persisted delta in storage:
  • New messages
  • New patches
  • Metadata version increment
  1. Check plugin phase behavior if execution is phase-dependent:
  • BeforeInference
  • BeforeToolExecute
  • AfterToolExecute
  1. Reproduce with minimal deterministic inputs and compare event traces.

Verify

A fix is effective when:

  • The same input no longer reproduces the failure.
  • Event sequence and terminal reason are stable across repeated runs.
  • Persisted thread state matches expected messages and patch history.

Common Errors

  • Debugging only final text output and ignoring event stream.
  • Inspecting latest thread snapshot but not patch delta/version movement.
  • Mixing protocol-encoded events with canonical AgentEvent semantics.
  • examples/ai-sdk-starter/README.md includes thread-history verification that is useful when debugging replay and persistence issues
  • examples/copilotkit-starter/README.md includes persisted-thread and canvas flows that surface event-ordering and approval issues quickly

Key Files

  • crates/tirea-agentos/src/runtime/loop_runner/mod.rs
  • crates/tirea-agentos-server/src/http.rs
  • crates/tirea-agentos-server/tests/run_api.rs