Agent-Xray: Open-source tool for debugging AI agent failures from trace logs
Agent-Xray is an open-source tool for debugging AI agents by analyzing their trace logs. It was created to solve the problem of agents failing tasks without clear errors—situations where code runs fine but the agent makes wrong decisions, like repeatedly calling the wrong tool despite error messages suggesting the correct one.
Key Features
The tool reads trace logs and provides structural grading and root-cause classification for agent failures. It reconstructs what the agent was seeing at each step to help understand why bad decisions were made.
Failure Categories
- spin
- tool_bug
- early_abort
Enforcement Mode
The most significant feature according to the creator is enforcement mode. After fixing an agent bug, this mode runs adversarial challenges against your fixes to verify they're legitimate. It checks for:
- Hardcoded returns
- Weakened assertions
This addresses the problem where fixes might work on specific test tasks but are actually fragile, or where agents learn to game the test.
Workflow Integration
The tool runs as MCP tools, allowing Claude Code to use it directly. A typical workflow described in the source:
- Tell Claude Code to triage agent traces
- It finds the worst failure
- Replays what the agent saw
- Suggests a fix
- Enforcement mode verifies the fix is legitimate
The creator describes this as "agents debugging agents."
Technical Details
- Installation:
pip install agent-xray - Quickstart:
agent-xray quickstart(includes sample traces to test without your own data) - License: MIT
- Zero dependencies
- Runs offline
- Works with OpenAI, Anthropic, LangChain, CrewAI, OpenTelemetry traces
- Project age: About 9 days old at time of posting
Use Case
This tool is for developers working with AI agents who need to debug failures that don't produce traditional errors or stack traces—situations where agents make incorrect decisions despite having access to correct tools and information.
📖 Read the full source: r/ClaudeAI
👀 See Also
Tokenless API Gateway Routes AI Traffic Between Models to Cut Spend in Half
Tokenless is an API gateway that dynamically routes AI agent requests turn-by-turn between models. It matches Claude Fable 5 performance at half the cost by fanning out to multiple models and selecting the best one mid-generation.
AutoBe: How Weak Local LLMs Fixed an AI Backend Generator's Architecture
AutoBe is an open-source AI agent that generates complete backend apps using TypeScript, NestJS, and Prisma. The team discovered their initial 100% compilation success produced unmaintainable code, then rebuilt with modular generation—crashing success to 40%—and used weak local LLMs like qwen3-30b-a3b-thinking to debug schema ambiguities.
Akemon: Publish and Hire AI Coding Agents Directly from Your Laptop
Akemon is a tool that lets developers publish their AI coding agents with one command and hire others' agents with another, working directly from laptops through a relay tunnel without needing servers. It's protocol-agnostic, supporting agents from Claude Code, Codex, Gemini, OpenCode, Cursor, and Windsurf.
Pixel Agents: 24 Specialized Claude Agents for Code, Site, and Resume Reviews
Pixel Agents is a collection of 24 task-specific AI agents built on Claude Sonnet 4.6 API, each with tuned personalities and structured JSON output. The system includes code review, site analysis, resume critique, and startup evaluation agents that provide direct feedback.