PtcRunner.SubAgent.Debug (PtcRunner v0.5.1)

Debug helpers for visualizing SubAgent execution.

Provides functions to pretty-print execution traces and agent chains, making it easier to understand what happened during agent execution.

Raw Mode

Use print_trace(step, raw: true) to see the complete LLM interaction:

Raw Input: Messages sent to the LLM (excluding system prompt)
Raw Response: Full LLM output including reasoning
Lines shown exactly as-is (no wrapping or truncation)

For all messages including the system prompt, use messages: true instead. Note: messages: true wraps long lines to 160 chars.

View Modes

View	Description
`:turns` (default)	Show programs + results from Turn structs
`:compressed`	Show what the LLM sees (compressed format)

Examples

# Default compact view
{:ok, step} = SubAgent.run(agent, llm: llm)
SubAgent.Debug.print_trace(step)

# Include raw input and raw response
SubAgent.Debug.print_trace(step, raw: true)

# Show all messages including system prompt
SubAgent.Debug.print_trace(step, messages: true)

# Show compressed view (what LLM sees)
SubAgent.Debug.print_trace(step, view: :compressed)

# Print agent chain
SubAgent.Debug.print_chain([step1, step2, step3])

Summary

Functions

print_chain(steps)

Pretty-print a chain of SubAgent executions.

print_trace(step, opts \\ [])

Pretty-print a SubAgent execution trace.

Functions

print_chain(steps)

@spec print_chain([PtcRunner.Step.t()]) :: :ok

Pretty-print a chain of SubAgent executions.

Shows the flow of data between multiple agent steps in a pipeline.

Parameters

steps - List of %Step{} structs representing a chain

Examples

iex> step1 = PtcRunner.SubAgent.run!(agent1, llm: llm)
iex> step2 = PtcRunner.SubAgent.then!(step1, agent2, llm: llm)
iex> PtcRunner.SubAgent.Debug.print_chain([step1, step2])
:ok

print_trace(step, opts \\ [])

@spec print_trace(
  PtcRunner.Step.t(),
  keyword()
) :: :ok

Pretty-print a SubAgent execution trace.

Displays each turn with its program, tool calls, and results in a formatted box-drawing style.

Parameters

step - A %Step{} struct with trace data
opts - Keyword list of options:
- view - :turns (default) or :compressed - perspective to render
- raw - Include raw input (messages, excluding system prompt) and raw response (default: false)
- messages - Show all messages sent to LLM including system prompt (default: false)
- usage - Show token usage, tool call statistics, and compression summary (default: false)

Examples

# Default compact view
iex> {:ok, step} = PtcRunner.SubAgent.run(agent, llm: llm, context: %{})
iex> PtcRunner.SubAgent.Debug.print_trace(step)
:ok

# Include raw LLM response
iex> PtcRunner.SubAgent.Debug.print_trace(step, raw: true)
:ok

# Show compressed view
iex> PtcRunner.SubAgent.Debug.print_trace(step, view: :compressed)
:ok

# Show messages sent to LLM (verify compression)
iex> PtcRunner.SubAgent.Debug.print_trace(step, messages: true)
:ok

# Show token usage
iex> PtcRunner.SubAgent.Debug.print_trace(step, usage: true)
:ok