See inside every agent run.

AgentOBSDebug ships developer tools for inspecting, replaying, and visualising AgentOBS traces. Span trees, execution timelines, tool-call analysis, cost attribution, and side-by-side trace diffs — via a Python API or a single CLI command.

AgentOBS SDK →Validate events →

Installation

Install in seconds.

Requires Python ≥ 3.10 and agentobs >= 1.0.5.

pip install agentobs-debug

Quickstart · CLI

Start from the terminal.

All AgentOBSDebug functionality is accessible from the agentobs-debug CLI. Point it at any JSONL file produced by the AgentOBS SDK.

bash

TRACE="4bf92f3577b34da6a3ce929d0e0e4736"

# Step-by-step replay
agentobs-debug replay events.jsonl --trace $TRACE

# Span hierarchy tree
agentobs-debug tree events.jsonl --trace $TRACE

# Execution timeline
agentobs-debug timeline events.jsonl --trace $TRACE

# Per-span cost/latency breakdown
agentobs-debug attribution events.jsonl --trace $TRACE

# Diff two traces
agentobs-debug diff events.jsonl \
  --trace-a $TRACE \
  --trace-b aaaa0000000000000000000000000001

Quickstart · Python API

Or use it programmatically.

Import agentobs_debug and call the same functions from your test suite, notebooks, or automation scripts.

python

import agentobs_debug as aod

stream = aod.load_events("events.jsonl")
trace  = "4bf92f3577b34da6a3ce929d0e0e4736"

# Single-trace inspection
aod.inspect_trace(trace, stream=stream)
aod.print_trace_tree(trace, stream=stream)
aod.timeline(trace, stream=stream)

# Cost analysis
aod.cost_summary(trace, stream=stream)
aod.cost_attribution(trace, stream=stream)

# Tool and decision analysis
aod.show_tools(trace, stream=stream)
aod.show_decisions(trace, stream=stream)

# Multi-trace
from agentobs_debug.report import batch_report
from agentobs_debug.diff import diff_traces

batch_report("events.jsonl")
diff_traces(trace, "other-trace-id", stream=stream)

API Reference

All functions at a glance.

Every function accepts a trace_id string and a stream (the output of load_events()). Output format defaults to text; pass output_format="json" for machine-readable output.

replay(trace, stream)Step-by-step interactive replay of an agent run. Prints each span in chronological order.

inspect_trace(trace, stream)Compact summary of a trace: span count, total cost, duration, model, and status breakdown.

print_trace_tree(trace, stream)Renders the parent–child span hierarchy as an indented tree.

timeline(trace, stream)ASCII timeline of span start/end across wall-clock time. Accepts from_ms / to_ms filters.

show_tools(trace, stream)Lists every tool call in the trace with name, arguments, result, latency, and any errors.

show_decisions(trace, stream)Decision-point summary: decision name, confidence score, outcome, and associated span.

cost_summary(trace, stream)Token usage and USD cost totals across the trace, broken down by model.

cost_attribution(trace, stream)Per-span cost and latency table with percentile breakdowns.

batch_report(path)Summarises every trace in a JSONL file — counts, totals, error rates.

diff_traces(trace_a, trace_b, stream)Side-by-side structural diff of two traces. Highlights added/removed/changed spans.

CLI Reference

agentobs-debug commands.

Command	Arguments	Description
replay	events.jsonl --trace <id>	Step-by-step replay of a single trace.
inspect	events.jsonl --trace <id>	Print a trace summary.
tree	events.jsonl --trace <id>	Print the span hierarchy tree.
timeline	events.jsonl --trace <id>	Print the execution timeline.
tools	events.jsonl --trace <id>	List all tool calls.
decisions	events.jsonl --trace <id>	List all decision points.
cost	events.jsonl --trace <id>	Print cost summary.
attribution	events.jsonl --trace <id>	Per-span cost/latency breakdown.
report	events.jsonl	Batch summary across all traces.
diff	events.jsonl --trace-a --trace-b	Diff two traces side-by-side.

Next steps

Confident events are compliant events.

Use AgentOBSValidate to enforce schema compliance in CI, catch drift at build time, and verify HMAC chains before shipping.

AgentOBSValidate →Back to the SDK →

← Python SDK AgentOBSValidate →