에이전트·RAG

AGENT / 67번째 글

에이전트가 무엇을 했는지 나중에 알 수 있게 만들기

에이전트는 같은 입력에도 다른 경로로 갑니다. 그래서 로그 몇 줄로는 왜 그렇게 됐는지 복원이 안 됩니다. 트레이스를 어떻게 나누고 구간마다 무엇을 붙이며 어떤 지표를 볼지 정리합니다.

PALDYN Team29 MIN READ

지난 글의 마지막 문단에서 「재기 전에는 줄이지 않는다」고 했는데, 그 재는 일이 이 글의 주제다. 그리고 비용만의 문제가 아니다. 비용을 재려고 남긴 기록이 곧 품질을 묻고, 사고를 따라가고, 고친 것을 확인하는 데 쓰인다. 무엇을 어떤 모양으로 남겨 두느냐가 나중에 던질 수 있는 질문의 범위를 정한다.

같은 입력, 다른 경로

백엔드와의 차이

일반적인 백엔드에서는 로그 몇 줄이면 대개 무슨 일이 있었는지 복원된다. 요청이 들어오고, 함수가 불리고, 응답이 나간다. 같은 입력이면 같은 길로 간다. 그래서 문제가 된 요청을 개발 환경에서 한 번 더 보내 보면 같은 오류가 다시 나고, 거기서부터 디버거를 붙이면 된다. 로그는 그 재실행을 돕는 보조 자료에 가깝다.

에이전트는 그렇지 않다. 에이전트는 모델이 다음에 할 일을 고르고, 도구를 부르고, 그 결과를 보고 다시 고르는 일을 끝날 때까지 되풀이한다. 이 되풀이 한 바퀴가 걸음이다. 걸음마다 모델이 다음 행동을 새로 정하므로 같은 입력에도 다른 걸음을 밟고, 걸음 수도 다르고, 도구를 부르는 순서도 다르다. 온도를 0으로 낮춰도 이 성질은 남는다 — 도구가 돌려주는 바깥 세계의 값이 어제와 오늘 다르기 때문이다. 검색 결과가 한 줄만 바뀌어도 모델이 그다음 걸음에서 고르는 행동이 달라지고, 그 차이가 뒤쪽 걸음으로 갈수록 커진다.

최종 응답만 남을 때

「어제 오후에 이 고객 문의에서 왜 저런 답이 나왔나」를 묻는 순간, 남아 있는 것이 최종 응답 한 줄뿐이면 답할 방법이 없다. 다시 돌려도 같은 길로 안 간다. 다시 돌려서 멀쩡한 답이 나오면 오히려 더 곤란하다. 문제가 없어진 것이 아니라 문제를 볼 길이 없어진 것이기 때문이다.

이때 답하지 못하는 질문은 하나가 아니다. 모델이 잘못 판단했는지, 도구가 틀린 값을 돌려줬는지, 앞 걸음의 결과를 뒤 걸음이 잘못 읽었는지, 상한에 걸려 중간에 멈춘 것을 끝난 것처럼 포장했는지 — 원인이 될 수 있는 자리가 걸음마다 있고, 최종 응답에는 그중 어느 것의 흔적도 남지 않는다. 사용자가 「답이 이상하다」고 알려 왔을 때 개발자가 할 수 있는 일이 추측밖에 없다면 그 시스템은 운영되고 있는 것이 아니라 그냥 돌아가고 있는 것이다.

기록과 질문의 범위

그래서 관측을 설계할 때의 출발점은 「무엇을 남길까」가 아니라 「나중에 무엇을 묻게 될까」다. 몇 번째 걸음에서 방향이 틀어졌는지를 묻고 싶으면 걸음마다 기록이 있어야 하고, 지난주보다 비용이 왜 늘었는지를 묻고 싶으면 호출마다 토큰 수가 있어야 한다. 남기지 않은 것에 대해서는 나중에 물을 수 없다. 그리고 대부분의 질문은 사고가 난 뒤에 처음 떠오르므로, 그때 가서 기록을 더하면 이미 늦다. 첫날 넣어 두는 것이 가장 싸다.

트레이스의 세 겹

트레이스와 구간

기록의 기본 단위는 두 낱말로 부른다. 구간은 시작 시각과 끝 시각을 가진 한 토막의 일이고, 다른 구간을 안에 품을 수 있다. 트레이스는 한 요청이 처음부터 끝까지 지나간 구간들을 같은 id로 묶은 것이다. 구간이 부모와 자식으로 이어지므로 트레이스는 나무 모양이 된다.

에이전트에서는 이 나무를 세 겹으로 쌓는다. 작업 하나가 트레이스 하나이고, 걸음 하나가 구간 하나이며, 그 안에 모델 호출과 도구 호출이 각각 자식 구간으로 들어간다.

에이전트 한 번 도는 것을 어떻게 남기는가

걸음 층

LLM 운영 관측에서 다룬 구조와 같은 것이고, 에이전트에서 달라지는 부분은 가운데 층이다. 단발 호출에는 걸음이라는 것이 없으니 트레이스 안에 호출 하나만 들어간다. 에이전트에서는 걸음 층이 있어야 「몇 번째 걸음에서 방향이 틀어졌나」를 물을 수 있다.

걸음 층을 빼고 모델 호출과 도구 호출을 트레이스 바로 아래에 나란히 붙여도 기록은 남는다. 그런데 그러면 스무 개의 호출이 한 줄로 늘어서고, 어느 도구 호출이 어느 모델 판단의 결과인지를 시각만 보고 짐작해야 한다. 걸음 구간이 그 둘을 한 묶음으로 쥐고 있으면 「걸음 4의 모델이 검색을 골랐고, 검색이 빈 결과를 돌려줬고, 걸음 5의 모델이 그 빈 결과를 보고 같은 검색을 다시 골랐다」가 위아래로 읽힌다. 걸음마다 「이번 걸음의 목표」를 한 줄 붙여 두면 더 좋다. 모델이 무엇을 하려 했는지와 실제로 무엇을 했는지가 나란히 놓인다.

길이와 위치

이렇게 겹쳐 놓으면 두 가지가 공짜로 따라온다. 어디가 느렸는지가 구간의 길이로 보이고, 어느 걸음에서 실패해 어디서 회복했는지가 구간의 위치로 보인다. 그림의 걸음 2에서 write가 시간 초과로 죽고 걸음 3에서 다시 성공한 것이 한눈에 읽힌다.

길이로 읽는 것은 대개 예상과 다르다. 에이전트가 느리다는 불평을 받으면 모델 호출부터 의심하기 쉬운데, 트레이스를 펼쳐 보면 도구 하나가 응답을 기다리며 걸음 전체의 절반을 쓰고 있는 경우가 흔하다. 위치로 읽는 것은 회복의 모양이다. 실패한 걸음 바로 다음에 회복이 오면 재시도가 잘 돌고 있는 것이고, 실패 뒤에 전혀 다른 방향의 걸음이 서너 개 이어지면 모델이 실패를 잘못 해석해 엉뚱한 길로 간 것이다. 둘 다 최종 성공으로 끝날 수 있지만 비용과 위험은 크게 다르다.

구간의 속성

구간별 필수 항목

구간에 시간만 남으면 「느렸다」까지는 알고 「왜」는 모른다. 구간마다 붙이는 이름-값 쌍을 속성이라고 부르는데, 종류마다 붙일 것이 다르다.

구간 반드시 남길 것
작업(트레이스) 작업 id, 사용자·테넌트, 요청 원문, 최종 상태, 총 걸음·토큰·비용
걸음 걸음 번호, 이번 걸음의 목표, 결과 상태
모델 호출 모델 이름과 버전, 프롬프트 버전, 입력·출력 토큰, 캐시 적중, 온도 등 설정
도구 호출 도구 이름, 인자, 결과 크기, 성공 여부와 오류

표의 위쪽은 묶어서 보기 위한 것이고 아래쪽은 원인을 찾기 위한 것이다. 작업 층의 사용자·테넌트가 있어야 「특정 고객사에서만 실패가 몰린다」가 보이고, 총 비용이 있어야 비싼 작업을 골라낼 수 있다. 아래 두 층은 그렇게 골라낸 작업을 열었을 때 무엇이 일어났는지를 말해 준다. 속성 이름은 팀 안에서 한 벌로 정해 둔다. 어떤 서비스는 model, 다른 서비스는 model_name으로 남기면 둘을 함께 묶는 질의가 매번 손으로 짜야 하는 일이 되고, 그러다 보면 아무도 묶어 보지 않는다.

모델 버전과 프롬프트 버전

모델 버전과 프롬프트 버전이 가장 자주 빠지고 가장 아쉬운 자리다. 지난주와 이번 주의 성공률이 다를 때 「모델이 바뀐 것인지 프롬프트를 고친 것인지」를 물으면, 이 둘이 안 남아 있으면 답이 없다. 모델 제공자가 같은 이름 아래에서 내부 판을 바꾸는 일도 있으므로 이름만이 아니라 응답에 실려 오는 정확한 버전 문자열을 남긴다. 프롬프트 버전 관리에서 다룬 버전 표시를 호출마다 함께 남긴다.

두 값이 있으면 배포 하나하나가 실험이 된다. 프롬프트를 고친 날을 경계로 성공률과 걸음 수를 갈라 보면, 그 수정이 무엇을 바꿨는지가 따로 시험을 돌리지 않아도 운영 기록에서 나온다. 반대로 한 번에 모델과 프롬프트를 함께 바꾸면 이 기록이 있어도 둘을 가를 수 없다 — 기록을 남기는 습관은 배포를 하나씩 끊어 내보내는 습관과 짝을 이룬다.

도구 인자

도구 인자도 남긴다. 「검색을 3번 했다」보다 「같은 질의를 조금씩 바꿔 3번 했다」가 훨씬 많은 것을 말해 준다. 앞의 것은 정상일 수도 있지만 뒤의 것은 모델이 원하는 것을 못 찾고 헤매고 있다는 뜻이다. 인자 없이는 두 상태를 구분할 수 없다. 결과 크기도 같은 이유로 남긴다. 도구가 수만 토큰짜리 결과를 돌려줘 다음 모델 호출의 입력이 부푼 자리는 비용 그래프에서 먼저 보이는데, 결과 크기가 없으면 그 원인이 어느 도구인지 다시 뒤져야 한다.

전문 보존

양쪽의 비용

입력·출력 전문을 어디까지 남길 것인가는 결정이 필요한 자리다. 다 남기면 저장 비용과 개인정보 문제가 생기고, 안 남기면 재현이 안 된다. 에이전트의 전문은 단발 호출보다 훨씬 크다. 걸음마다 그때까지의 대화와 도구 결과가 통째로 입력에 다시 들어가므로, 열 걸음짜리 작업 하나의 입력을 다 모으면 같은 문서가 열 번 겹쳐 저장된다. 하루 수만 건이면 이것만으로 저장 비용이 모델 비용을 따라잡는다.

개인정보 쪽은 더 무겁다. 고객이 문의에 적은 주소와 전화번호, 도구가 사내 시스템에서 꺼내 온 계정 정보가 전부 전문 안에 있다. 관측 도구는 대개 개발자 여럿이 넓게 들여다보는 곳이라, 거기에 원문이 그대로 쌓이면 운영 시스템보다 관측 시스템이 더 큰 유출 창구가 된다.

전문과 지표의 보존 기간을 나눠 잡는 방식

보존 기간과 표본

실무에서 자리 잡은 절충은 무게가 다른 기록을 다른 기간 동안 두는 것이다.

  • 전문은 짧은 보존 기간(예: 2주)으로 따로 저장하고, 지표와 메타데이터는 오래 남긴다
  • 실패한 작업은 보존 기간을 길게 잡는다. 다시 볼 확률이 압도적으로 높다
  • 트래픽이 크면 성공한 작업은 일부만 표본으로 전문을 저장하고, 실패한 작업은 전량 저장한다

표본을 뽑을 때는 작업이 시작될 때가 아니라 끝났을 때 정하는 편이 낫다. 시작할 때 1%를 고르면 실패한 작업의 99%가 전문 없이 끝난다. 끝난 뒤에 상태를 보고 고르면 실패는 전부, 성공은 일부를 남길 수 있다. 전문을 잠시 붙잡아 두었다가 작업이 끝난 순간 버릴지 넘길지 정하는 모양이 된다.

마스킹

개인정보는 저장 전에 마스킹한다. 마스킹은 이름·전화번호·계정 번호 같은 값을 찾아 다른 표시로 바꿔 쓰는 처리이고, 저장 뒤가 아니라 저장 전에 해야 관측 시스템에 원문이 한 번도 안 닿는다. 마스킹한 자리는 [이름]처럼 무엇이 지워졌는지 표시가 남게 한다. 그냥 지우면 「모델이 주소를 빠뜨린 것」과 「우리가 주소를 지운 것」을 나중에 구분할 수 없다. 표시가 남아 있으면 그 자리에 무엇이 있었는지는 몰라도 무엇의 자리였는지는 안다.

마스킹은 도구 인자에도 건다. 모델이 고객의 전화번호로 사내 조회 도구를 부르면 그 번호가 도구 구간의 인자에 그대로 남는다. 전문만 마스킹하고 속성을 빠뜨리면, 오래 보관하는 쪽인 메타데이터에 개인정보가 쌓이는 역전이 생긴다. 무엇을 찾아 바꿀지는 정규식 같은 규칙으로 시작하고, 놓친 자리가 발견될 때마다 규칙을 더한다. 완벽하게 거르는 방법은 없으므로 관측 시스템 자체의 열람 권한도 함께 좁혀 둔다.

지표와 알림

작업 성공률

트레이스가 개별 사건을 설명한다면 지표는 전체가 어디로 가고 있는지를 본다. 그 첫 줄이 작업 성공률이다. 「끝났다」가 아니라 「제대로 끝났다」의 비율인데, 이 정의를 정하는 것이 절반의 일이다. 에이전트는 실패해도 대개 그럴듯한 문장으로 끝나므로 예외가 안 난 것을 성공으로 세면 성공률이 늘 98%쯤에 붙어 아무것도 말해 주지 않는다. 사용자가 같은 질문을 곧바로 다시 했는지, 사람에게 넘겨졌는지, 결과를 코드로 검사했을 때 형식이 맞았는지처럼 바깥에서 확인되는 신호를 하나 이상 성공의 조건에 넣는다.

성공률은 작업 종류마다 따로 센다. 환불 문의와 배송 조회가 한 숫자에 섞이면, 쉬운 쪽이 늘어나는 날 전체 성공률이 올라 어려운 쪽이 나빠진 것을 덮는다. 작업 층에 요청 종류를 속성으로 붙여 두면 이 가르기가 질의 한 줄로 끝난다. 종류를 처음부터 정확히 나누지 못해도 괜찮다 — 거칠게 셋넷으로만 나눠 둬도 평균에 묻히는 일은 대부분 막힌다.

분포로 보는 값

나머지 값들은 평균이 아니라 분포로 본다.

  • 걸음 수 분포 — 오른쪽 꼬리가 길어지면 종료 판단이 흔들리고 있다는 뜻이다
  • 작업당 비용의 분포 — 같은 이유로 평균이 아니라 분포다
  • 도구별 실패율 — 어느 도구가 루프를 망가뜨리는지 가장 빨리 알려 준다
  • 사람 개입률 — 게이트에서 거부된 비율. 0이거나 너무 높으면 둘 다 신호다
  • 끝까지 못 간 비율 — 상한에 걸려 멈춘 작업의 비율

분포를 한 숫자로 줄일 때는 95백분위를 쓴다. 작업 백 건을 걸음 수 순으로 세웠을 때 아흔다섯 번째 작업의 값이다. 걸음 수 분포를 특히 권하는데, 이 하나로 잡히는 문제가 많다. 평균 6걸음이던 것이 평균 6.4로 조금 오르고 95백분위가 12에서 25로 뛰었다면, 대부분은 그대로인데 어떤 종류의 요청이 루프에 빠지기 시작한 것이다. 평균만 보면 안 보인다. 백 건 중 다섯 건이 13걸음씩 더 걸으면 평균은 0.65 오를 뿐이다.

변화 기준 알림

지표를 모아 두면 자연스럽게 알림 이야기가 나오는데, 여기서 흔한 실수가 절대 기준을 거는 것이다. 「성공률 90% 미만이면 알림」식으로 걸어 두면 처음부터 88%인 작업 종류가 하나 있어서 알림이 늘 켜져 있게 되고, 곧 아무도 안 본다. 에이전트에서 실제로 유용한 알림은 대개 변화에 걸린 것이다.

  • 걸음 수 95백분위가 지난주 대비 1.5배가 됐다
  • 특정 도구의 실패율이 어제 대비 3배가 됐다
  • 상한에 걸려 멈춘 작업이 하루 5건을 넘었다
  • 작업당 평균 비용이 이틀 연속 올랐다

마지막 것이 조용한 사고를 가장 잘 잡는다. 품질이 그대로여도 비용이 오르고 있으면 뒤에서 무언가가 늘어나고 있다는 뜻이다. 도구 결과가 조금씩 길어지거나, 캐시가 어느 배포에서 깨졌거나, 특정 요청이 한두 걸음씩 더 걷기 시작한 것이다. 알림이 울리면 그날 비용이 가장 많이 든 작업 몇 개의 트레이스를 열어 보는 것으로 시작한다 — 지표가 어디를 볼지 알려 주고, 트레이스가 무엇이 일어났는지 알려 주는 분업이다.

변화를 잴 때 무엇과 견줄지도 정해 둔다. 어제와 견주면 요일마다 들쭉날쭉한 트래픽이 그대로 알림이 되고, 지난달 평균과 견주면 천천히 나빠지는 것이 기준선에 섞여 안 보인다. 같은 요일의 지난주 값이 가장 무난한 기준선이다. 그리고 배포 직후 몇 시간은 따로 본다. 프롬프트나 모델을 바꾼 직후의 변화는 원인이 이미 알려져 있으므로, 거기서 울리는 알림은 끄는 대신 배포 기록 옆에 붙여 두면 다음 배포 때 비교 자료가 된다.

재현

재현의 세 재료

정리하면 관측의 목표는 무슨 일이 있었는지 보는 것이 아니라 재현, 곧 그 상황을 다시 만들 수 있는 것이다. 다음 셋이 남아 있으면 대개 재현이 된다.

  • 시작 상태 — 요청 원문과 그때의 시스템 프롬프트·도구 정의
  • 각 걸음의 입력과 출력 — 모델에 실제로 들어간 것과 나온 것
  • 바깥 세계의 응답 — 도구가 돌려준 것

셋째가 가장 자주 빠진다. 도구 결과를 남겨 두지 않으면 재실행할 때 도구를 다시 불러야 하는데, 그사이 바깥 세계가 바뀌어 같은 결과가 안 온다. 앞에서 에이전트가 같은 입력에도 다른 길로 가는 이유가 바깥 세계였으니, 그 세계의 응답을 기록해 두는 것이 그 흔들림을 붙잡는 유일한 방법이다.

실험 환경 재실행

이 셋이 있으면 문제가 된 작업을 실험 환경에서 그대로 다시 돌려 볼 수 있다. 도구 호출 자리에 실제 도구 대신 기록된 응답을 끼워 넣고, 문제가 된 걸음까지 기록대로 진행한 뒤 거기서부터 고친 프롬프트로 바꿔 돌리면 된다. 그러면 고친 프롬프트가 바로 그 상황을 해결하는지를 확인할 수 있다. 「비슷한 질문을 몇 개 넣어 봤더니 괜찮더라」보다 훨씬 강한 확인이다.

다만 기록된 응답으로 돌리는 재실행에는 한계가 있다. 고친 프롬프트 때문에 모델이 원래와 다른 도구를 고르거나 다른 인자로 부르면, 그 호출에 맞는 기록이 없다. 이 지점부터는 실제 도구를 부르거나 「기록 없음」으로 멈추는 수밖에 없다. 그래서 재실행은 문제가 된 걸음까지는 기록으로, 그 뒤는 실제 도구로 가는 반반 모양이 되기 쉽고, 쓰기 도구처럼 바깥을 바꾸는 호출은 실험 환경에서 반드시 막아 둔다. 그래도 문제가 된 걸음 자체를 같은 입력으로 다시 세울 수 있다는 것만으로 원인을 좁히는 일의 대부분이 끝난다.

회귀 시험 자료

그렇게 모은 실패 작업들이 그대로 에이전트 평가의 회귀 시험 자료가 된다. 평가 자료를 따로 만들 때 가장 어려운 것이 실제 사용자가 던지는 이상한 요청을 떠올리는 일인데, 운영 기록에는 그것이 이미 쌓여 있다. 관측을 제대로 하면 평가 자료가 저절로 쌓인다는 것이 이 작업의 가장 큰 이득이다. 그리고 기록이 쌓이고 나면 다음으로 물을 것은 실패가 어디서 시작되느냐다 — 한 걸음 안의 어느 자리에서 어긋나고, 그것이 어떤 증상으로 번지는지가 다음 글의 이야기다.

정리

  • 에이전트는 같은 입력에도 다른 길로 가므로 「다시 돌려 보기」로는 원인을 못 찾는다
  • 작업 하나가 트레이스, 걸음 하나가 구간, 그 안에 모델 호출과 도구 호출을 각각 구간으로 둔다
  • 걸음 층이 있어야 「몇 번째에서 틀어졌나」를 물을 수 있다. 단발 호출 관측과 달라지는 지점이다
  • 모델 버전과 프롬프트 버전이 가장 자주 빠지고 가장 아쉽다. 호출마다 남긴다
  • 도구 인자를 남겨야 「같은 질의를 반복하고 있다」가 보인다
  • 전문은 짧게, 지표는 길게. 실패한 작업은 보존 기간을 따로 길게 잡는다
  • 개인정보는 저장 전에 마스킹하되 무엇이 지워졌는지 표시를 남긴다
  • 평균이 아니라 분포를 본다. 걸음 수 95백분위 하나로 잡히는 문제가 많다
  • 알림은 절대 기준이 아니라 변화에 건다. 늘 켜져 있는 알림은 없는 것과 같다
  • 목표는 관찰이 아니라 재현이다. 재현할 수 있으면 실패 사례가 그대로 평가 자료가 된다

읽어주셔서 감사합니다. 😊

LATEST

에이전트·RAG의 최신 글

에이전트·RAG2026.08.23

에이전트에 사람을 어디까지 붙일 것인가

승인 버튼을 걸음마다 두면 아무도 그 에이전트를 쓰지 않고, 하나도 안 두면 사고가 납니다. 게이트를 놓을 세 자리와 어느 걸음에 무엇을 걸지 정하는 순서를 정리합니다.

13 MIN
에이전트·RAG2026.08.22

몇 시간, 며칠씩 도는 에이전트를 어떻게 버티게 하는가

몇 분이면 끝나던 에이전트가 몇 시간짜리 일을 맡으면 전에 없던 문제가 생깁니다. 상태를 어디에 둘지, 체크포인트를 어디에 남길지, 같은 걸음을 두 번 밟아도 안전하게 만들려면 무엇이 필요한지 정리합니다.

14 MIN
에이전트·RAG2026.08.22

에이전트끼리 일을 넘길 때 무엇을 함께 넘기는가

여럿으로 나눈 에이전트가 기대만큼 못 하는 이유는 대개 넘기는 자리에 있습니다. 대화를 통째로 넘기는 방식이 왜 나쁜지, 봉투에 무엇을 담아야 하는지, 돌려받는 쪽에 무엇이 있어야 하는지 정리합니다.

31 MIN