# `PtcRunner.SubAgent.Debug`
[🔗](https://github.com/andreasronge/ptc_runner/blob/main/lib/ptc_runner/sub_agent/debug.ex#L1)

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.

## 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 (the LLM's actual view)
    SubAgent.Debug.print_trace(step, messages: true)

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

# `print_chain`

```elixir
@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`

```elixir
@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:
  - `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 compaction 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 messages sent to LLM
    iex> PtcRunner.SubAgent.Debug.print_trace(step, messages: true)
    :ok

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*