관측 가능성과 디버깅: 에이전트가 밟는 모든 단계를 들여다보기

이 코스는 에이전트가 실제로 무엇을 했는지 보는 일을 다룹니다. 앞 코스(이 시리즈의 열 번째)가 '통과했는가'를 매듭지었습니다. 종료 상태 채점, 검증기, 평가 세트가 그것입니다. 그런데 평가는 통과냐 실패냐만 건네줍니다. 사용자가 '뻔히 거기 있는 정보를 못 찾는다'고 알려 와도 여전히 왜 그런지는 말할 수 없습니다. 검색어가 잘못 쓰였을까요? 출처를 잘못 골랐을까요? 도구가 그냥 에러를 냈을까요? 밖에서 보면 그 원인들은 똑같아 보입니다. 게다가 에이전트는 실행마다 비결정적이라 같은 프롬프트가 두 번 돌면 두 갈래 길을 가고, '재현한 다음 중단점을 걸어라'라는 전통적인 디버깅 본능은 그대로 멈춰 섭니다. 이 코스는 '말할 수 없다'를 '찾아볼 수 있다'로 바꾸는 법을 가르칩니다. 먼저 원본 트랜스크립트(도구 호출과 응답이 오간 전체 왕복)가 1차 증거이고 에이전트의 자기 보고는 증거가 되지 못한다는 것을 세웁니다. 그다음 하네스에 구조화된 로그와 메트릭을 답니다(소요 시간, 호출 수, 토큰, 에러 — 이번에는 채점이 아니라 프로덕션을 지켜보기 위해서입니다). 그다음 흩어진 기록을 상관관계 ID로 꿰어 트레이스 트리로 만들어, 프롬프트 하나가 촉발한 모든 모델 요청과 도구 실행이 한 덩어리로 읽히게 합니다. 그다음 훅으로 루프의 검문소에 탐침을 놓는 법과 비결정성을 전제하고 짠 디버깅 워크플로를 익힙니다. 끝으로 코스7 하네스에 관측 가능성 계층 전체를 배선하고, '말할 수 없다'는 증상 하나를 잘못된 바로 그 단계까지 따라갑니다. 이 시리즈의 앞 열 개 코스를 마친 독자를 위한 코스입니다. 이 코스는 특정 관측 플랫폼을 가르치지 않고(Datadog이나 Grafana 같은 것은 인용이 이름을 대는 자리에서만 언급합니다), 알림 임계값이나 SLO 설계도 다루지 않으며(1차 자료가 아무 수치도 주지 않습니다), 코스10의 평가 방법도 되풀이하지 않습니다. 거기서는 메트릭이 채점하고, 여기서는 같은 메트릭이 진단합니다.

코스 구성

학습 목표

이 코스를 마치면 다음을 할 수 있습니다:

비결정성이 '재현한 다음 디버깅한다'를 어떻게 무너뜨리는지 설명하기: 같은 프롬프트가 서로 다르지만 똑같이 정당한 두 길을 가고, 밖에서는 구별되지 않는 여러 원인 위에 증상 하나가 얹혀 있다
원본 트랜스크립트를 1차 증거로 쓰기: 도구 호출과 응답이 오간 전체 왕복을 읽고, 에이전트의 사고 사슬과 자기 보고가 결코 언급하지 않는 행동을 잡아내고, 자기 보고를 믿을 수 없는 이유를 설명하기
자기 하네스를 위한 구조화된 로그와 메트릭을 설계하기: 모델 요청마다 그리고 도구 호출마다 기록 하나씩, 소요 시간과 호출 수와 토큰과 에러를 담기 — 그리고 공식 문서의 진단적 읽기를 써서 메트릭의 양상을 구체적인 수정으로 옮기기
흩어진 기록을 상관관계 ID로 꿰어 트레이스 트리로 만들기: 프롬프트 하나가 촉발한 모든 것이 한 덩어리로 읽히고 서브에이전트가 부모 트레이스 안에 중첩된다 — 그리고 텔레메트리 파이프라인 자체가 어떻게 거짓말하는지 알기(조용한 실패, 배치 유실)
루프의 생명주기 검문소에 탐침을 놓기: 세션마다·턴마다·도구 호출마다의 관측 지점을 갈라 두고, PostToolUse로 완전한 호출 기록을 붙잡고, prompt id로 거르기 → 첫 분기점 찾기 → 동일한 입력으로 단계별 재생이라는 흐름을 따라 문제의 위치를 좁히기
코스7 하네스에 완전한 관측 가능성 계층을 배선하고(JSONL 구조화 로그 + 트레이스 트리 출력 + 메트릭 요약), 디버깅 드릴 하나를 처음부터 끝까지 걸어 보기: 증상 → 거르기 → 위치 특정 → 수정 → 재실행 비교(실제 실행은 실패 지점에서 이어 갑니다)

사전 지식

이 시리즈의 앞 열 개 코스를 마쳤거나 그에 준하는 지식이 있다
stop_reason이 이끄는 하네스 루프를 직접 손으로 쓸 수 있고 tool_use/tool_result 짝 맞추기를 이해한다(코스7)
평가 트랙과 통과율 너머의 메트릭을 안다(코스10. 이 코스는 같은 메트릭을 채점에서 진단으로 옮깁니다)
기본적인 JavaScript / Node.js 코드를 읽고 쓸 수 있다(레슨6에서는 함께 써 나갑니다)

예상 학습 시간

각 레슨의 실습 연습을 포함해 약 3~4시간.