Agent-Xray: Open-Source-Tool zum Debuggen von KI-Agent-Fehlern aus Trace-Logs

Agent-Xray ist ein Open-Source-Tool zum Debuggen von KI-Agenten durch die Analyse ihrer Trace-Protokolle. Es wurde entwickelt, um das Problem zu lösen, dass Agenten Aufgaben ohne klare Fehlermeldungen nicht erfüllen – Situationen, in denen der Code einwandfrei läuft, der Agent aber falsche Entscheidungen trifft, wie etwa das wiederholte Aufrufen des falschen Tools, obwohl Fehlermeldungen das richtige nahelegen.

Hauptfunktionen

Das Tool liest Trace-Protokolle und bietet strukturelle Bewertung und Ursachenklassifizierung für Agentenfehler. Es rekonstruiert, was der Agent in jedem Schritt gesehen hat, um zu verstehen, warum schlechte Entscheidungen getroffen wurden.

Fehlerkategorien

• Spin
• Tool-Bug
• Early-Abort

Enforcement-Modus

Die bedeutendste Funktion laut dem Ersteller ist der Enforcement-Modus. Nach der Behebung eines Agenten-Fehlers führt dieser Modus adversarische Herausforderungen gegen Ihre Korrekturen aus, um zu überprüfen, ob sie legitim sind. Er prüft auf:

• Hartkodierte Rückgaben
• Abgeschwächte Assertions

Dies behebt das Problem, dass Korrekturen bei bestimmten Testaufgaben funktionieren könnten, aber tatsächlich fragil sind, oder dass Agenten lernen, den Test zu umgehen.

Workflow-Integration

Das Tool läuft als MCP-Tools, sodass Claude Code es direkt nutzen kann. Ein typischer Workflow laut der Quelle:

1. Claude Code anweisen, Agenten-Traces zu triagieren
2. Es findet den schwerwiegendsten Fehler
3. Spielt wieder, was der Agent gesehen hat
4. Schlägt eine Korrektur vor
5. Der Enforcement-Modus überprüft, ob die Korrektur legitim ist

Der Ersteller beschreibt dies als "Agenten, die Agenten debuggen".

Technische Details

• Installation: pip install agent-xray
• Schnellstart: agent-xray quickstart (enthält Beispiel-Traces zum Testen ohne eigene Daten)
• Lizenz: MIT
• Keine Abhängigkeiten
• Läuft offline
• Funktioniert mit OpenAI-, Anthropic-, LangChain-, CrewAI-, OpenTelemetry-Traces
• Projektalter: Etwa 9 Tage zum Zeitpunkt der Veröffentlichung

Anwendungsfall

Dieses Tool ist für Entwickler gedacht, die mit KI-Agenten arbeiten und Fehler debuggen müssen, die keine traditionellen Fehler oder Stack-Traces erzeugen – Situationen, in denen Agenten trotz Zugriff auf korrekte Tools und Informationen falsche Entscheidungen treffen.