PtcRunner.SubAgent.Debug (PtcRunner v0.4.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.

Debug Option

Enable debug mode via the :debug option on SubAgent.run/2:

{:ok, step} = SubAgent.run(agent, llm: llm, debug: true)

When debug mode is enabled, trace entries store the exact message contents:

llm_response - The assistant message (LLM output, stored as-is)
llm_feedback - The user message (execution feedback, after truncation)

These are exactly what's in the messages array sent to the LLM. Use print_trace(step, messages: true) to view this data.

Trace Option

Control trace collection via the :trace option:

Value	Behavior
`true` (default)	Always collect trace
`false`	Never collect trace
`:on_error`	Only include trace on failure

Examples

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

# Show full LLM messages (requires debug: true)
SubAgent.Debug.print_trace(step, messages: true)

# 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:
- messages: true - Show full LLM response and feedback (requires debug: true during execution)
- system: true - Show the system prompt in each turn (default: false when messages: true)
- usage: true - Show token usage summary after the trace

Examples

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

# Show full LLM messages (requires debug: true during execution)
iex> {:ok, step} = PtcRunner.SubAgent.run(agent, llm: llm, debug: true)
iex> PtcRunner.SubAgent.Debug.print_trace(step, messages: true)
:ok

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