에이전트-Xray: 추적 로그에서 AI 에이전트 실패를 디버깅하는 오픈소스 도구

Agent-Xray는 AI 에이전트의 추적 로그를 분석하여 디버깅하는 오픈소스 도구입니다. 이 도구는 코드는 정상적으로 실행되지만 에이전트가 잘못된 결정을 내리는 상황—예를 들어 오류 메시지가 올바른 도구를 제안함에도 불구하고 계속해서 잘못된 도구를 호출하는 경우—처럼 명확한 오류 없이 작업이 실패하는 문제를 해결하기 위해 만들어졌습니다.

주요 기능

이 도구는 추적 로그를 읽고 에이전트 실패에 대한 구조적 등급 평가 및 근본 원인 분류를 제공합니다. 각 단계에서 에이전트가 무엇을 보고 있었는지 재구성하여 잘못된 결정이 왜 내려졌는지 이해하는 데 도움을 줍니다.

실패 범주

• spin
• tool_bug
• early_abort

강제 모드

제작자에 따르면 가장 중요한 기능은 강제 모드입니다. 에이전트 버그를 수정한 후, 이 모드는 수정 사항이 합법적인지 확인하기 위해 적대적 도전을 실행합니다. 다음을 확인합니다:

• 하드코딩된 반환값
• 약화된 단언문

이는 수정 사항이 특정 테스트 작업에서는 작동하지만 실제로는 취약하거나, 에이전트가 테스트를 속이는 방법을 배우는 문제를 해결합니다.

워크플로우 통합

이 도구는 MCP 도구로 실행되어 Claude Code가 직접 사용할 수 있습니다. 소스에서 설명한 일반적인 워크플로우:

1. Claude Code에게 에이전트 추적을 분류하라고 지시
2. 가장 심각한 실패를 찾음
3. 에이전트가 본 내용을 재생
4. 수정 사항을 제안
5. 강제 모드가 수정 사항이 합법적인지 확인

제작자는 이를 "에이전트가 에이전트를 디버깅한다"고 설명합니다.

기술적 세부사항

• 설치: pip install agent-xray
• 빠른 시작: agent-xray quickstart (자체 데이터 없이 테스트할 수 있는 샘플 추적 포함)
• 라이선스: MIT
• 의존성 없음
• 오프라인 실행 가능
• OpenAI, Anthropic, LangChain, CrewAI, OpenTelemetry 추적과 호환
• 프로젝트 기간: 게시 시점 기준 약 9일

사용 사례

이 도구는 전통적인 오류나 스택 추적을 생성하지 않는 실패를 디버깅해야 하는 AI 에이전트 작업 개발자를 위한 것입니다—에이전트가 올바른 도구와 정보에 접근할 수 있음에도 불구하고 잘못된 결정을 내리는 상황입니다.