A trajectory is the path an agent takes toward a goal: its intermediate reasoning steps, tool-call sequence, and final response. An execution trace records that path for a single request. A correct answer alone cannot show whether the agent followed a reasonable, efficient route or succeeded despite a mistake. section 10.2.1 section 10.1.1
A trace can be broken into spans and events. Spans represent work such as an LLM call, tool invocation, memory read, or planning step. Events mark occurrences within that work, such as an exception or the start of a retry. Metrics show measurable behavior; logs record details; traces connect the activity into a request-wide flow. section 10.1.1
Use trajectories at two levels:
- Debug one run: inspect the trace to find where reasoning or tool use went wrong, rather than judging only the final answer. section 4.8.2
- Evaluate many runs: collect traces for representative requests, review recurring failures, and turn the most important patterns into evaluation criteria. section 10.2 section 10.2.1
A plausible answer can hide a bad path
Suppose a tool call fails, but the agent claims it succeeded and continues to a plausible answer. Reviewing the trace exposes the first error: tool-result hallucination. Likewise, an agent may reach the right answer only after unnecessary calls or backtracking. Both cases require examining the path, not just the output. section 10.2 section 10.2.1
Listing 4.34 Debugging with execution traces
from scratch_agents.utils import display_trace
agent = create_gaia_agent(models[0], mcp_tools)
result = await agent.run(
"If Eliud Kipchoge could maintain his marathon pace, "
"how many thousand hours to reach the Moon?"
)
print(f"Answer: {result.output.final_answer}")
print(f"Steps: {result.context.current_step}")
display_trace(result.context)
This Python example runs a tool-enabled agent, prints its answer and step count, then passes the result’s execution context to display_trace() for inspection. section 4.8.2
