콘텐츠로 이동

P7-12.1 agent trace로 도구 호출과 멈춤 지점을 다시 읽기

Section ID: P7-12.1 Version: v2026.07.31

P7-11에서는 AI 에이전트(AI agent)의 계획, 도구 호출, 승인, blocked 상태를 실행 기록으로 나누었습니다. 다음 확장 질문은 그 기록을 사람이 손으로 적는 수준을 넘어, 실행 trace로 다시 읽을 수 있는가입니다.

agent 관측성(observability) 실습의 목적은 새 대시보드를 꾸미는 것이 아닙니다. Part 7에서는 trace를 어떤 도구가 어떤 입력으로 호출되었는가, 어디서 지연이나 실패가 생겼는가, 어느 단계가 승인 때문에 멈췄는가, 다음 실행에서 무엇을 바꿔야 하는가를 확인하는 실행 증거로 다룹니다.

trace는 최종 답변의 품질 평가와 다릅니다. 최종 답변만 보면 성공했다 또는 실패했다로 보이지만, trace를 보면 실패가 잘못된 입력, 도구 출력 부족, 권한 대기, 시간 초과, 사용자 승인 필요 가운데 어디에 가까운지 나눌 수 있습니다. 이 구분이 있어야 agent를 더 많이 자동화할지, 반대로 멈춤 지점을 더 명시적으로 둘지 판단할 수 있습니다.

trace가 남겨야 할 것

agent 실행 trace에는 최소한 다음 정보가 남아야 합니다.

항목 확인할 질문
계획 단계 실행 전에 어떤 하위 작업으로 나누었는가?
도구 호출 어떤 도구를 어떤 입력으로 호출했는가?
출력 요약 도구 출력이 다음 판단에 충분했는가?
권한 상태 자동 실행, 승인 필요, 보류 중 무엇이었는가?
지연과 실패 오래 걸린 단계와 실패한 단계가 어디인가?
다음 행동 재시도, 입력 수정, 승인 요청, 중단 중 무엇인가?

이 표는 P7-11.2의 권한 로그와 비슷해 보이지만, 관측성 실습에서는 사람이 정리한 회고뿐 아니라 실행 시스템이 남긴 trace와 대조합니다.

span은 실행을 다시 읽는 최소 단위다

OpenTelemetry 계열의 관측성 도구에서는 실행의 한 구간을 span으로 기록합니다. Part 7에서는 이 용어를 복잡한 관측성 인프라의 시작점으로 다루지 않고, 한 번의 하위 작업을 나중에 다시 읽을 수 있게 자른 단위로 봅니다. agent 실행에서는 계획 생성, 검색, 파일 읽기, 도구 호출, 승인 대기, 결과 요약이 각각 span이 될 수 있습니다.

span 후보 남겨야 할 값 실패했을 때 볼 질문
plan 작업 분해, 선택한 순서 계획이 너무 큰 단위였는가
retrieve 검색어, 후보 수, 선택 문서 필요한 정보가 검색되었는가
tool_call 도구 이름, 입력, 상태 입력이 잘못되었는가, 도구가 실패했는가
approval_wait 요청한 권한, 대기 상태 자동 실행하면 안 되는 단계였는가
summarize 사용한 근거, 최종 판단 도구 출력이 답변에 제대로 반영되었는가

span을 작게 나누는 이유는 세밀한 로그를 많이 남기기 위해서가 아닙니다. 다음 실행에서 바꿀 수 있는 단위로 실패를 잘라 두기 위해서입니다. tool_call span이 실패했으면 입력과 도구 상태를 보고, approval_wait span에서 멈췄으면 재시도보다 승인 요청이나 작업 범위 축소를 먼저 봅니다.

실행 기록 예시

step tool status permission observation next_action
1 search_docs completed auto 관련 문서 3개 검색 요약 단계 진행
2 update_config blocked approval_required 배포 설정 변경 필요 사용자 승인 요청
3 run_check skipped blocked_by_step_2 승인 전 실행 불가 승인 뒤 재개

이 기록에서 중요한 결론은 agent가 실패했다가 아닙니다. 멈춘 지점은 설정 변경 권한이고, 다음 행동은 재시도가 아니라 승인 요청입니다. trace는 실패를 더 작은 실행 단위로 나누어 다음 조치를 분명하게 만듭니다.

blocked와 failure를 나누어 읽기

agent 실행에서 blocked와 failure를 같은 실패로 묶으면 위험합니다. failure는 실행을 시도했지만 기대한 결과를 얻지 못한 상태입니다. blocked는 실행을 계속하기 전에 권한, 정보, 환경, 사용자 판단이 필요한 상태입니다.

상태 의미 다음 행동
completed 실행이 끝났고 다음 판단에 쓸 출력이 있다 출력 검토 후 다음 단계 진행
failed 실행했지만 오류나 부적절한 출력이 났다 입력 수정, 도구 변경, 재시도
blocked 실행 전 또는 중간에 필요한 조건이 비어 있다 승인 요청, 정보 요청, 범위 축소
skipped 앞 단계 상태 때문에 실행하지 않았다 원인 단계가 풀린 뒤 재개 여부 판단

예를 들어 배포 설정을 바꾸는 도구 호출이 승인 대기 때문에 멈췄다면, 그것은 실패라기보다 blocked입니다. 여기서 자동 재시도를 반복하면 같은 지점에서 다시 멈춥니다. trace가 남겨야 하는 핵심은 재시도 횟수가 아니라, 멈춤이 정당한 안전 장치였는지와 다음 행동이 무엇인지입니다.

trace를 회고 문장으로 바꾸기

trace는 그대로 두면 로그 묶음일 뿐입니다. Part 7의 프로젝트 기록으로 쓰려면 마지막에 짧은 회고 문장으로 바꾸어야 합니다.

trace에서 본 사실 해석 다음 질문
검색 도구는 성공했지만 선택 문서가 부족했다 계획보다 정보 수집 범위가 좁았다 검색어를 넓히거나 질문을 나눌 것인가
설정 변경 단계가 승인 대기에서 멈췄다 자동 실행 경계가 적절히 작동했다 승인 요청 문구에 위험 범위가 충분히 담겼는가
점검 도구가 skipped 되었다 앞 단계가 풀리지 않아 검증이 불가능했다 blocked가 풀린 뒤 어떤 검사를 먼저 실행할 것인가

이렇게 바꾸면 agent trace는 운영 로그이면서 동시에 다음 실험의 설계 문서가 됩니다.

직접 바꿔 보며 확인할 것

  • 같은 작업에서 읽기 도구와 쓰기 도구를 분리하면 blocked 지점이 어떻게 달라지는가?
  • 실패한 tool call의 입력을 trace에서 다시 확인할 수 있는가?
  • 지연 시간이 긴 단계가 실제 오류 원인인지, 단순히 오래 걸린 정상 단계인지 구분되는가?
  • 승인 정책이 trace 안에서 명시적으로 남는가?

체크리스트

  • agent 실행을 최종 답변만으로 평가하지 않았는가?
  • tool call 입력, 출력, 상태가 단계별로 남았는가?
  • blocked와 failure를 같은 실패로 뭉뚱그리지 않았는가?
  • trace에서 다음 행동을 직접 도출할 수 있는가?

출처와 참고 자료