Captures what happened during an agent execution.
A trajectory is a sequence of Puck.Eval.Step structs representing each
LLM call made during the execution of an agent. Use Puck.Eval.Collector.collect/1
to automatically capture trajectories via telemetry.
Fields
:steps- List ofPuck.Eval.Stepstructs in execution order:total_steps- Count of steps:total_tokens- Sum of all tokens used:total_duration_ms- Total time for all LLM calls
Example
# Capture trajectory automatically
{output, trajectory} = Puck.Eval.Collector.collect(fn ->
MyAgent.run("Find John's email")
end)
trajectory.total_steps # => 2
trajectory.total_tokens # => 385
# Inspect individual steps
Enum.each(trajectory.steps, fn step ->
IO.puts("Action: #{inspect(step.output)}")
end)Summary
Functions
Adds a step to the trajectory.
Returns an empty trajectory.
Returns the first step in the trajectory, or nil if empty.
Returns the last step in the trajectory, or nil if empty.
Creates a new Trajectory from a list of steps.
Returns all outputs from the trajectory steps.
Types
@type t() :: %Puck.Eval.Trajectory{ steps: [Puck.Eval.Step.t()], total_duration_ms: non_neg_integer(), total_steps: non_neg_integer(), total_tokens: non_neg_integer() }
Functions
Adds a step to the trajectory.
Returns a new trajectory with the step appended and totals recalculated.
Returns an empty trajectory.
Returns the first step in the trajectory, or nil if empty.
Returns the last step in the trajectory, or nil if empty.
Creates a new Trajectory from a list of steps.
Automatically calculates total_steps, total_tokens, and total_duration_ms
from the provided steps.
Example
steps = [
Step.new(input: "Hello", output: "Hi", tokens: %{total: 10}, duration_ms: 100),
Step.new(input: "Bye", output: "Goodbye", tokens: %{total: 15}, duration_ms: 80)
]
trajectory = Trajectory.new(steps)
trajectory.total_steps # => 2
trajectory.total_tokens # => 25
trajectory.total_duration_ms # => 180Returns all outputs from the trajectory steps.