Execution Traces

An execution trace is the ordered list of steps an agent took during a run, with per-step timing and token usage.

The steps array

When you report a run you can include a steps array. Each step records one unit of work the agent performed. AgentPulse renders these as the run's execution trace, so you can see exactly where time and tokens went.

Step types

type	Meaning	Watch for
llm	A call to a language model.	Token count and duration — usually where cost and latency concentrate.
tool	An external function or API call.	Slow or failing downstream services.
retrieval	A fetch from a vector store or database.	Irrelevant context is a quiet cause of wrong answers.
reasoning	An intermediate planning step.	Why the agent chose its next action.

Step fields

Each step accepts type, name, duration_ms, and optional tokens and error. Only type is required; the more you send, the richer the trace.

Reading a trace

• Slow run? Find the step with the dominant duration_ms — latency is almost never spread evenly.
• Expensive run? Sort by tokens; look for one bloated LLM call or the same step repeating (a retry loop).
• Wrong answer? Read the trace as a story — a bad retrieval upstream usually explains a confidently wrong result.