- Getting started
- UiPath Agents in Studio Web
- UiPath Agents in Agent Builder
- UiPath Coded agents
Agents user guide
Traces
Traces are detailed records of everything an agent does during a run, including steps taken, data processed, decisions made, and results generated. Each trace captures a complete timeline of the agent’s behavior, including timestamps, errors, inputs/outputs, and contextual metadata.
Use traces for:
-
Debugging and troubleshooting: Identify exactly where an agent failed or behaved unexpectedly.
-
Performance analysis: Evaluate latency, errors, and throughput across agent runs to optimize behavior.
-
Compliance and auditing: Maintain a verifiable record of what the agent did, when, and how — essential for audits or regulated workflows.
-
Continuous improvement: Use trace insights to fine-tune agent logic, adapt behavior, or train new models.
The following table outlines common use cases where trace visualization can enhance your ability to debug, analyze, and optimize agent behavior. Each example highlights how trace data helps uncover insights and drive better decision-making during development and runtime monitoring.
| Use case | What traces help you do |
|---|---|
| Agent fails during tool call | Find and inspect the exact step, inputs, outputs, and error |
| Performance is slow | Use timestamps to locate bottlenecks |
| Investigating a spike in errors | Filter runs by status and trace the pattern |
| Verifying a production fix | Replay the original run and confirm the issue no longer occurs |
| Preparing an audit report | Export or review traces that show decision paths and data handled |
Traces come in two distinct types, each serving a specific purpose in understanding and analyzing agent behavior:
- Agent run traces: These traces capture the step-by-step execution of an agent during a live or scheduled run. They show how the agent processed data, invoked tools, handled conditions, and responded to different states in real-time.
- Evaluation run traces: Evaluation traces are generated when an agent is tested against predefined inputs, typically during model evaluations, scenario validations, or test cases. These help assess agent accuracy, decision quality, and behavior under controlled conditions.
You can access both types of traces from two key locations:
-
Agent Builder: While designing or editing an agent, switch to the Evaluations or Output tabs to inspect how the agent behaved during recent runs.
-
Agent Instances page: Navigate to the Agents > Instances section. From here, select a specific agent and select any run to open its trace view, which includes the full visual trace and log panel. For details, refer to Agent instances tab.
When viewing traces for either agent runs or evaluation runs, you gain visibility into the agent’s execution. You can:
-
See execution outcomes, as indicated with color-coded nodes: success, failure, or retry.
-
Hover over any node to preview: start and end timestamps, execution status, input and output snippets.
-
Click a node to view the details, including: complete JSON payloads, logs and errors, runtime metrics, (token usage, latency).
