Reading an Agent Trace

A trace is the full record of what an agent did and why. Reading traces is how you debug agents.

Tools like LangSmith, Traceloop, and Anthropic's Claude trace UI show every step the agent took, what tools it used, and what each tool returned.

Three things to look for in a trace

• Where the agent got the goal right or wrong
• Which tool calls failed silently
• How long each step took

The big idea: Reading traces is like being a detective — you reconstruct what the agent thought.

When an agent does something weird, the answer is in the trace — the log of every thought, tool call, and result. Tools like LangSmith, Langfuse, or even console.log let you see exactly where it went sideways.

Some examples

• You read a Claude trace and spot that the agent picked the wrong tool because the description was vague.
• Langfuse shows the agent looped six times because the stopping condition never matched.
• Console logs reveal the agent passed null to a tool because of a bad prior result.
• A LangSmith trace shows the model hallucinated a tool name that didn't exist in the schema.

Try it!

Add tracing (Langfuse, LangSmith, or just JSON.stringify) to your next agent. Run it. Read the trace.

Most agent frameworks log every thought and tool call. Reading these logs is how you fix agents.

Some examples

• Look for the step where the agent's plan changes for no reason.
• Check what the tool actually returned vs what the agent thought it returned.
• Find the prompt that confused it and fix that prompt.

Try it!

Pick any agent you've used. Find its trace/log. Read one full run end to end.

Understanding "Reading an agent trace like a detective" in practice: AI agents don't just answer questions — they can do things, like looking things up, writing files, or talking to apps. When an agent fails, the trace tells you where its brain broke — and knowing how to apply this gives you a concrete advantage.

• Design clear agent goals before adding tools
• Define permissions and scope before deploying any agent
• Build in human-approval checkpoints for high-stakes actions
• Understand when to use an agent vs. a simple chat prompt

1. 1Design an agent spec: goal, tools, permissions, stop condition
2. 2Run a simple web-search agent in a sandbox environment
3. 3Instrument an existing workflow to identify where an agent could save time