Trace an agent with tools

Agent traces get messy fast: multiple model calls, tool invocations, retries, and loops. The goal is to make the trace tree mirror the agent’s decision flow.

Recommended span tree

• agent.run (trace root)
  • retrieval.query (optional)
  • llm.plan (optional)
  • tool.execute (one per tool call)
  • llm.respond (final response)

Tool spans

For every tool call, record:

• tool name
• sanitized arguments
• result summary (or pointer to stored artifact)
• error + retry count

Loop safety

If the agent can loop, add:

• iteration metadata (0, 1, 2…)
• a maximum iteration guardrail
• a fallback flag if you switch to a cheaper model or safe response

Next steps

• Read Spans and Events.
• Add programmatic checks via Evaluations.