에이전트는 왜 그렇게 했는가

에이전트 시스템의 디버깅은 실행 기록을 읽는 일입니다. 기록이 없으면 손을 쓸 수 없습니다.

남겨야 할 것

항목	왜
각 단계의 입력·출력	어디서 틀어졌는지 찾는다
도구 호출과 인자	엉뚱한 도구·인자를 썼는지 본다
도구 응답	도구가 빈 값을 줘서 헤맨 것인지 구분한다
단계별 토큰·지연	비용과 병목을 찾는다
핸드오프 시점과 이유	왜 넘겼는지, 왜 안 넘겼는지
종료 사유	목표 달성인가, 한계 도달인가

마지막 항목이 특히 중요합니다. 한계에 걸려 멈춘 것을 완료로 착각하면 불완전한 결과를 신뢰하게 됩니다.

트레이스에서 찾는 신호

같은 도구를 반복 호출 — 결과를 이해하지 못해 계속 다시 부르는 상태입니다. 도구 응답 형식이 어렵거나 설명이 부실한 경우가 많습니다.

도구 응답이 빈 값인데 그대로 진행 — 데이터가 없는데 결론을 냈다면 그 결론은 추측입니다.

핸드오프 없이 한 에이전트가 끝까지 — 넘기는 조건이 모호해서 혼자 다 한 것입니다. 역할 분리가 무의미해집니다.

단계 수가 예상보다 많음 — 목표가 모호하거나 종료 조건이 불명확합니다.

로그를 사람이 읽을 수 있게

원본 로그는 길고 읽기 어렵습니다. 요약된 화면이 필요합니다.

• 단계를 시간 순으로 나열하고 각 단계의 한 줄 요약
• 도구 호출은 접어 두고 필요할 때 펼치기
• 토큰·지연은 막대로 표시해 병목이 눈에 보이게

시뮬레이터의 트레이스 화면이 이 구조를 따릅니다. 직접 보면서 무엇이 유용한지 확인하세요.