에이전트(agent)를 지시하는 것은 쉬운 절반에 불과합니다. 어려운 나머지 절반은 그들의 답변 중 어떤 것을 신뢰해야 할지 아는 것입니다.

저는 Claude Code에서 한 번에 10개씩 연구용 서브에이전트(subagent)를 펼쳐놓고 약 2주를 보냈는데, 병목 현상은 결코 출력을 생성하게 만드는 것이 아니었습니다. 모델은 후보를 생성하는 데는 능숙하지만, 무엇이 증거로 간주되는지 아는 데는 서툽니다. 따라서 10개의 백그라운드 에이전트가 각각 자신만만한 텍스트 더미를 반환할 때, 생성(generation)이 문제가 아닙니다. 검증(verification)이 문제입니다. 그리고 볼 수 없는 것은 검증할 수 없습니다. 마지막 에이전트가 보고를 마칠 때쯤이면, 흥미로운 세부 사항들은 아무도 읽지 않을 트랜스크립트(transcript) 속에 파묻혀 버립니다.

agentrace는 당신을 대신해 트랜스크립트를 읽어줍니다.

핵심 아이디어: 계측(instrumentation) 없음

제가 이 도구에서 가장 좋아하는 점은 사전에 추가할 것이 아무것도 없다는 것입니다. 래퍼(wrapper), SDK, 에이전트 호출 주변의 데코레이터(decorator)가 필요 없습니다. Claude Code는 이미 모든 세션을 ~/.claude/projects/<slug>/<session-id>.jsonl에 디스크로 기록하고 있으며, 해당 파일에는 모든 Agent 위임(delegation)과 그 결과가 이미 포함되어 있습니다. 데이터를 살펴볼 계획이었든 아니든 데이터는 디스크에 존재하며, 이는 사후에라도 추적(trace)하고 싶었던 실행 내용을 분석할 수 있음을 의미합니다.

따라서 agentrace는 런타임(runtime)이 아니라 리더(reader)입니다. 이 도구는 해당 JSONL 트랜스크립트를 파싱하고, 각 서브에이전트 호출을 그 결과와 쌍으로 묶은 다음, 해당 쌍에 대해 일련의 텍스트 휴리스틱(heuristics)을 실행하여 다시 살펴볼 가치가 있는 결과를 지목합니다.

무엇을 보여주는가

세 가지 명령어가 대부분의 작업을 수행합니다. 첫째, 집계(aggregate):

$ agentrace stats
 subagent runs          152
 errored                7
...

그다음 중요한 부분인 플래깅(flagging):

$ agentrace check
 36/152 runs flagged, 39 findings

이것들은 이 도구를 만들게 된 계기가 된 세션의 실제 수치입니다. 152개의 서브에이전트 실행이 포함된 34MB 크기의 트랜스크립트입니다. 플래그가 지정된 36개 중 7개는 탐색 도중 세션 제한으로 종료된 에이전트였고, 17개는 확신 없는 주장(hedged claims)이었으며, 12개는 출력 형태(output shape)를 지정하는 것을 잊은 프롬프트였습니다.

마지막 숫자가 바로 제가 계속해서 지적하고 있는 부분입니다. 대부분의 에이전트 툴링 (agent tooling)은 모델이 문제라고 가정합니다. 하지만 여기서 발생한 플래그 (flags) 중 3분의 1은 제 잘못이었습니다.

시야를 좁혀 단일 실행 (single run) 결과 전체를 읽어볼 수 있습니다:

agentrace list                  # 모든 실행: 설명, 소요 시간, 크기
agentrace check --severity high # 확실히 중요한 것들만 확인
agentrace check --strict        # 높은 위험도가 발견되면 종료 코드 1 반환 (CI 친화적)
...

체크 항목들은 실제 실패 사례에서 비롯되었습니다

모든 체크 항목은 그럴듯해 보여서가 아니라, 실제로 발생했기 때문에 존재합니다. 그중 몇 가지는 다음과 같습니다:

• error: 에이전트가 전체 스윕 (sweep) 도중 세션 제한으로 인해 중단됨. 작업 내용이 조용히 유실되었으며, 보고서가 누락된 상태로 돌아오기 전까지는 아무도 알아채지 못했습니다.
• absence_as_evidence: 에이전트가 API가 빈 리스트를 반환했다는 이유로 특정 회사가 채용 중이 아니라고 결론 내림. 해당 API는 존재하지 않는 계정에 대해 HTTP 200과 함께 빈 값을 반환합니다. 데이터의 부재가 부재의 증거는 아닙니다.
• gave_up:

모든 검사는 텍스트에 대한 휴리스틱 (heuristic)입니다. 이는 무엇을 읽어야 할지 알려줄 뿐, 무엇이 사실인지를 알려주지는 않습니다. 이 구분은 매우 중요합니다. 왜냐하면 양치기 소년처럼 잘못된 경고를 보내는 검사기는 아예 없는 것보다 더 나쁜 상황을 초래하여 결국 꺼지게 되기 때문입니다. 심지어 test_clean_run_produces_nothing이라는 테스트도 있는데, 이 테스트의 유일한 목적은 깨끗한 실행(clean run)에서 아무런 결과물(findings)도 생성되지 않도록 유지하는 것입니다.

이를 위해 튜닝(tuning)한 가장 명확한 사례는 다음과 같습니다: 기존의 thin_prompt는 200자 미만의 모든 프롬프트에 대해 경고를 발생시켰습니다. 하지만 "Run the suite and report every failing test as node ids with its assertion message"라는 문장은 113자이면서도 완전히 검증 가능합니다. 이를 플래그(flag)로 표시하는 것은 독자의 주의력만 소모할 뿐 누구에게도 아무것도 가르쳐주지 못했습니다. 결함은 길이가 아니었습니다. 결함은 짧으면서 수행 결과가 어떠해야 하는지를 전혀 명시하지 않는 것이었습니다. 따라서 이제는 두 가지 신호가 모두 충족되어야 합니다. 이 번들 피스처 (bundled fixture)를 통해 단 하나의 실제 결과물도 놓치지 않으면서 발견된 결과물을 16개에서 9개로 줄였습니다.

솔직한 한계

이것들은 힌트이지 판결이 아닙니다. 모든 결과물은 텍스트에 대한 휴리스틱 (heuristic)이므로, 양방향 모두에서 틀릴 수 있습니다. hedged_claim 플래그가 있다고 해서 그 주장이 거짓이라는 뜻은 아니며, 단지 완곡한 표현 (hedge)이 존재하며 하류 (downstream) 단계에서 평탄화될 수 있음을 의미할 뿐입니다. 플래그가 지정되지 않은 실행이 정답이라고 인증된 것은 아닙니다. 단지 7가지 패턴 중 어느 것도 건드리지 않았을 뿐입니다. agentrace는 인간이 어디를 살펴봐야 할지를 좁혀줍니다. 그것은 인간을 대체하지 않으며, 에이전트의 답변이 실제로 참인지 판단할 수도 없습니다. 판결을 원한다면, 여전히 agentrace가 가리키는 실행 내용을 직접 읽어야 합니다.

실시간 실행을 살펴보고자 하는 요구사항에 따라 몇 가지 파싱 (parsing) 선택이 뒤따랐습니다. 트랜스크립트 (transcript)를 두 번 스캔하는데, 이는 결과가 특이한 순서로 나타나기 전에 각 대응하는 사용 사례가 먼저 나타날 수 있기 때문이며, 페어링 (pairing)을 미묘하게 틀리는 것보다는 34MB 파일을 두 번 스캔하는 것이 비용이 훨씬 저렴하기 때문입니다. 여전히 추가되고 있는 세션의 찢어진 마지막 줄은 치명적인 오류로 처리하는 대신 건너뜁니다. 또한 결과가 아직 없는 실행도 사라지는 대신 표시되는데, 이는 종료되었거나 여전히 실행 중인 에이전트가 바로 당신이 보고 싶어 하는 대상이기 때문입니다.

결론

이 도구는 현재 작동하며, 17개의 테스트를 포함하고 있고, rich 외에는 의존성이 없으며, API 키나 네트워크 연결도 필요하지 않습니다. 오직 로컬 파일만 읽습니다. 만약 당신이 서브에이전트 (subagent)를 실행하면서, 그들이 내놓은 확신에 찬 답변을 직접 읽어보지 않고 그대로 배포한 적이 있다면, 이 도구는 바로 그 순간을 위해 제가 원했던 도구입니다.

Repo: https://github.com/royalpinto007/agentrace