Understand and review agent traces

When you instrument your AI agent with the Pendo Python or TypeScript SDK, you can send trace data alongside conversation events. Traces give you a detailed view of how your agent executes—not just what it said, but how it got there.

This article explains what tracing is, how it differs from conversation events, and how to view trace data in Pendo.

What tracing is

A trace is a record of everything your AI agent did to produce a response. While a conversation event captures the input (visitor prompt) and output (agent response), a trace captures the steps in between: the tools your agent called, the models it used, the order operations ran in, how long each step took, and where errors occurred.

Traces are made up of spans. Each span represents a single operation within your agent's execution, for example, a call to a language model, a tool invocation, or a retrieval step. Spans are nested to show which operations triggered others, giving you a full picture of your agent's behavior for any given response.

Traces versus conversation events

Both conversation events and trace data appear in Agent Analytics, but they answer different questions.

You don't need trace data to use Agent Analytics. Conversation events alone power use case detection, issue identification, conversation review, and most overview metrics. Tracing is an additional layer if you want more visibility into how your agents work.

Use cases

Tracing is useful when you want to:

• Understand why an agent gave a particular response.
• Identify which tools or models are being called most frequently.
• Debug failures or unexpected outputs by seeing exactly where execution broke down.
• Measure latency across individual steps in your agent's pipeline.
• Validate that agent behavior is consistent after making changes.

Prerequisites

To send and view trace data:

• Your agent must be instrumented with the Pendo Python or TypeScript SDK. For setup steps, see Install the Python SDK to send conversation and trace data and Install the TypeScript SDK to send conversation and trace data.
• Full conversations must be activated for your agent in Pendo.
• You must be a subscription admin or assigned the AI Agent Admin role to view conversation and trace data in Pendo.

View conversation traces

When trace data is available for a conversation, Pendo surfaces it in the conversation panel in Agent Analytics. This tracing capability is automatically activated by the Python and TypeScript SDKs' standard setup, requiring no additional configuration.

Access conversation traces

1. Go to Product > Agent Analytics.
2. Select the agent you want to review.
3. Open the Conversations tab.
4. Select a conversation from the table.
5. In the conversation panel, look for the View trace activity icon below a prompt or agent response. This indicates that trace data is available for that message. Select it to open the Conversation trace view.
   

What traces show

The conversation trace includes:

• Span tree. A hierarchical view of all operations that ran during the agent's response, showing which steps activated others.
• Waterfall timeline. A timeline view of each span, showing when it started, how long it ran, and how it overlapped with other operations.
• Error detection. Spans that produced errors are flagged, so you can identify exactly where execution failed.
• Input and output details. The input and output for each span, so you can trace data as it flows through your agent's pipeline.

Note: Conversation traces are only available for conversations where trace data was sent through the Python or TypeScript SDK. Conversations captured through the client-side or server-side methods don't include trace data.

Trace types

Every trace event includes an agentTraceType field that categorizes the specific operation being recorded. Use this field to understand what each span in the trace view represents.