Our docs got a refresh! Check out the new content and improved navigation. For detailed API reference see our Python SDK docs and TypeScript SDK.
Description
Percival

Percival Debugging Overview

Automated agent debugging that detects errors and suggests optimizations

Percival is an intelligent agent debugger that detects 20+ failure modes in agentic traces and suggests optimizations for your systems. Teams building agentic AI typically spend countless hours combing through traces and logs to find planning mistakes, incorrect tool calls, and wrong outputs. Percival makes this process fast and reliable—with a single click, it analyzes full agent workflows, surfaces failure modes, and suggests prompt improvements to fix them.

Unlike traditional evaluation approaches like LLM-as-a-judge or curated test datasets that catch mistakes at specific points, Percival analyzes the full agentic execution to identify systemic issues like flawed planning or misused tools, even when traces are long or complex.

Percival can be activated by clicking "Analyze with Percival" on any trace. The image above shows a cluster of errors and prompt optimizations to prevent repeated tool calls.

How Percival works

Percival is an adaptive learning agent that analyzes traces to generate actionable insights. Here's what it does:

  1. Ingests traces - Processes spans from your agent workflows
  2. Analyzes execution - Identifies errors, inefficiencies, and optimization opportunities
  3. Clusters errors - Groups similar failures together for systematic resolution
  4. Recommends fixes - Suggests concrete prompt improvements
  5. Scores traces - Rates execution on a 1-5 scale for security, reliability, and other dimensions
  6. Learns continuously - Stores insights in memory, episodically (what tools have previously been called in traces) and semanticly (human-provided feedback on agents), to improve analysis over time

This adaptive approach allows Percival to understand any system and provide increasingly accurate insights as it learns from your traces and feedback.

How to get started

  1. Set up tracing for your agent workflows

    Add the @traced decorator to your existing agent or follow an example workflow.

  2. Navigate to the Traces tab

  3. Click "Analyze with Percival"

  4. Review generated insights

    Read the summary, explore error clusters, and review prompt optimization suggestions.

Framework integrations

Percival's trace parser relies on OpenTelemetry and OpenInference tracing conventions. The following frameworks are supported out of the box:

Next steps

Previous

Concepts

Next

Error Taxonomy

On this page