whatbroke — 에이전트 도구 호출과 트레이스 차이 비교 도구

작성자는 저장소 링크를 공유하며 도구가 침묵성 버그를 찾아냈을 때 사례를 보내달라고 요청했다. 게시물 자체에는 다른 사용자 반응이나 댓글 내용이 포함되지 않으므로 구체적 커뮤니티 피드백은 본문에서 확인되지 않는다. 작성자가 피드백을 수집하려는 의도와 공개 라이선스 정책은 추가 검증과 기여를 유도할 수 있는 구조로 보인다.

• 변경 전후의 에이전트 실행을 JSONL 트레이스로 저장하고 whatbroke diff를 활용하면 텍스트 출력 변화 없이 발생한 도구 호출 누락이나 인자 변경을 검증할 수 있다. 프록시 모드를 사용하면 애플리케이션 코드를 수정하지 않고도 다양한 언어의 트래픽을 캡처할 수 있으므로 테스트 환경 구성 비용을 낮출 수 있다. CI 파이프라인에 whatbroke의 종료 코드 1 동작을 연결하면 무심코 배포된 회귀를 자동으로 차단하는 방어선이 만들어진다.
• 동일 시나리오를 여러 번 기록해 flap rate를 산출하면 본래부터 변동하던 행동은 우선순위에서 낮춰 실제 변경의 신호를 선별할 수 있다. 로컬 오프라인 저장을 유지하면 민감한 API 키나 사용자 데이터가 외부로 유출되는 위험을 회피할 수 있으며 MIT 라이선스 하에 도구를 내부 워크플로에 맞게 포크해 확장할 수 있다. 도구를 적용할 때는 트레이스 포맷과 수집 지점이 서비스의 외부 상태 변경 지점을 모두 포괄하는지 확인하는 것이 중요하다.

JSONL(줄 단위 JSON)(JSONL)

— JSONL은 각 행에 하나의 JSON 객체를 저장하는 형식이다. 로그나 트레이스처럼 반복적인 이벤트를 순차적으로 기록하고 파싱하기에 효율적이며 라인 단위 병행 처리나 스트리밍이 쉽다. 이 도구는 에이전트 실행 결과를 JSONL 트레이스로 보존하고 변경 전후를 비교하는 목적으로 JSONL을 사용한다.

프록시 모드(Proxy Mode)

— 프록시 모드는 기존 클라이언트가 변경 없이 HTTP 엔드포인트를 가리키게 하여 요청과 응답을 가로채는 방식이다. 네트워크 레이어에서 호출 정보를 캡처해 애플리케이션 코드 변경 없이 트레이스를 생성할 수 있다는 점이 핵심이다. whatbroke는 이 방식으로 다양한 언어 환경에서 트레이스 기록을 수집하게 설계되어 있다.

변동률(Flap Rate)(Flap Rate)

— Flap rate는 동일한 시나리오를 여러 번 실행했을 때 결과가 달라지는 비율을 의미한다. 에이전트의 비결정적 행동을 수량화해 변경 전후의 차이가 기존 변동 범위에 포함되는지 판단하는 근거로 사용된다. whatbroke는 이 수치를 기반으로 본래부터 변동하던 차이는 중요도에서 낮춰 표시한다.

도구 호출(Tool Calls)

— 도구 호출은 에이전트가 외부 함수나 API를 작동시키기 위해 발생시키는 행동으로서 호출된 엔드포인트, 전달된 인자, 응답이 핵심 데이터이다. 에이전트 애플리케이션에서는 도구 호출이 실제 외부 효과를 내므로 호출 누락 또는 인자 변경이 침묵성 버그로 이어진다. whatbroke는 도구 호출의 시퀀스와 인자 차이를 트레이스 비교의 주요 단위로 삼는다.

CI 연동(CI Integration)

— CI 연동은 변경점이 자동화된 파이프라인에서 테스트되도록 하는 구성으로서 실패 시 빌드나 배포를 중단한다. whatbroke는 변경 탐지 시 종료 코드 1을 반환하여 기존 CI 워크플로에 장애 신호로 통합되도록 설계되어 있다. 이 동작은 무심코 배포된 침묵성 결함을 사전에 차단하는 데 목적이 있다.