도입 상담 신청
블로그 목록 도입과 관리

AI 에이전트 작업 기록·이력 관리, 원인 추적에 남길 10개 항목

AI 에이전트 작업 기록·이력 관리, 원인 추적에 남길 10개 항목

AI 에이전트 작업 기록으로 문제 원인을 추적하려면 결과물만으로는 부족합니다. 실행을 묶는 식별자, 지시문과 모델의 판, 도구 호출 성공 여부와 오류 유형, 승인·거부 결정 주체를 함께 남깁니다.

이 항목들이 이력 관리 체계 안에서 서로 이어져 있으면 이상 신호가 보일 때 원인 후보를 몇 개로 좁힐 수 있습니다. 예를 들어 검수에서 원고 문제가 보이면, 그 원고의 실행 식별자로 당시 지시문 판과 도구 호출 결과를 함께 불러옵니다.

원인을 추적할 수 있는 기록은 결과 기록과 무엇이 다른가요?

결과 기록은 「무엇이 만들어졌는가」를 남깁니다. 원인 추적용 기록은 「그 결과가 어떤 입력과 판단을 거쳐 나왔는가」를 남깁니다. 게시된 글 한 편에 문제가 있을 때 결과 기록만 있으면 글을 다시 읽는 방법밖에 없습니다. 과정 기록이 있으면 어느 단계에서 어긋났는지 확인할 수 있습니다.

공식 도구 문서도 한 번의 요청에서 생긴 기록을 식별자로 묶는 방식을 씁니다. OpenAI Agents SDK 문서는 워크플로 한 번의 처음부터 끝까지를 트레이스(trace, 한 번의 실행 흐름 전체 기록)로 묶는다고 설명합니다. 그 안의 개별 동작은 시작·종료 시각을 가진 스팬(span, 개별 동작 기록)으로 남습니다.

스팬 종류에는 모델 응답 생성, 함수 도구 호출, 가드레일(입력·출력을 검사하는 안전 장치), 핸드오프(다른 에이전트로 넘김)가 있습니다. 같은 문서에 따르면 trace_id는 지정하지 않으면 자동으로 만들어지고, group_id로 같은 대화에서 나온 여러 트레이스를 연결할 수 있습니다.

Claude Code 모니터링 문서는 prompt.id를 사용자 요청 하나를 처리하는 동안 생긴 모든 이벤트를 잇는 식별자로 설명합니다. 이 값으로 걸러 내면 요청 이벤트와 그에 따른 모델 요청·도구 결과 이벤트가 함께 나옵니다. 실무에서는 사내 작업 번호(예: 글 한 편의 작업 번호)를 이 식별자들과 짝지어 같은 표에 남기는 방법을 권합니다.

실행 한 번마다 어떤 항목을 남겨야 하나요?

원인 추적에 쓰는 항목은 아래 표의 열 가지입니다. 「확인할 질문」 열은 문제가 생겼을 때 그 항목으로 답할 수 있는 질문입니다.

기록 항목남길 내용확인할 질문
실행 식별자도구가 만든 실행 번호와 사내 작업 번호이 결과는 어느 실행에서 나왔는가
묶음 식별자같은 작업에 속한 여러 실행을 잇는 번호재작성·재검수가 몇 회차까지 갔는가
지시문 판지시문·검수 기준의 판 번호와 변경일그때 어떤 규칙으로 일했는가
모델과 에이전트 판모델 이름, 에이전트 이름과 판지난번과 같은 조건이었는가
입력 자료자료 위치, 받은 시각, 자료 건수근거가 빠진 채 작성되지 않았는가
도구 호출도구 이름, 성공 여부, 오류 유형, 소요 시간실패한 호출 뒤에도 작업이 이어졌는가
승인·거부 결정결정 내용과 결정 주체(설정·사람)누가 이 동작을 허용했는가
사용량입력·출력 토큰(모델이 글을 처리하는 단위) 수, 요청 횟수반복 호출이 생기지 않았는가
산출물 판원고·수정본의 판 번호와 저장 위치게시본이 승인본과 같은가
외부 반영게시 시각, 바꾼 페이지 주소, 반영자사이트 변경이 언제 일어났는가

표의 항목 상당수는 공식 도구가 이미 기록합니다. Claude Code 문서에 따르면 tool_result 이벤트에는 도구 이름, 성공 여부, 소요 시간, 오류 유형이 담깁니다. tool_decision 이벤트에는 수락·거부 결정과 그 출처가 남습니다.

출처는 설정(규칙·권한 모드), 훅(특정 시점에 자동 실행되는 사용자 정의 명령), 사용자의 상시 허용·일회 허용·거부·응답 없이 닫기로 구분됩니다. api_request 이벤트에는 모델 이름, 입력·출력 토큰 수, 요청 번호가 들어갑니다.

다만 이 문서는 텔레메트리(사용 기록을 외부 수집기로 보내는 기능) 수집을 별도 환경 변수로 켜야 한다고 안내합니다. 사용 전에 켜져 있는지 먼저 확인합니다.

OpenTelemetry의 생성형 AI 에이전트 스팬 규약은 현재 개발(Development) 단계입니다. 이 규약의 에이전트 생성 스팬에서 에이전트 ID·이름·판, 요청 모델, 오류 유형(error.type)은 모두 조건부 필수 속성입니다. 값이 있거나 작업이 오류로 끝났을 때 기록한다는 뜻입니다.

같은 규약은 메모리 안에서 잠깐 쓰이는 에이전트 인스턴스 ID를 기록하지 않도록 권합니다. 실무에서는 실행 때마다 바뀌는 값 대신 계속 유지되는 에이전트 이름과 판 번호를 기록하는 방법을 권합니다.

이상 신호가 보이면 어떤 원인 후보부터 확인하나요?

이상 신호 하나에는 원인 후보가 여러 개 있습니다. 아래 표는 SEO·GEO 운영에서 나타날 수 있는 신호와 먼저 열어 볼 기록 항목을 짝지은 것입니다. 「먼저 볼 기록 항목」은 앞에 적힌 것부터 차례로 확인합니다.

이상 신호원인 후보먼저 볼 기록 항목
같은 지시인데 결과 품질이 갑자기 달라짐모델 판 변경, 지시문 판 변경모델과 에이전트 판, 지시문 판
원고에 출처 없는 수치가 들어감입력 자료 누락, 자료 수집 도구 실패 뒤 작업 계속입력 자료 건수, 도구 호출 성공 여부
작업이 중간에 멈추거나 산출물이 비어 있음권한 거부, 모델 요청 오류 반복승인·거부 결정, 오류 유형과 재시도 횟수
사용량이 평소보다 크게 늘어남같은 단계의 반복 호출, 입력 자료 과다사용량, 묶음 식별자 안의 실행 수
게시된 내용이 승인한 원고와 다름승인 뒤 수정본 반영, 저장 위치 혼동산출물 판, 외부 반영 기록
같은 글이 두 번 게시됨재실행 시 작업 번호 중복, 예약 중복실행 식별자, 묶음 식별자
게시 뒤 검색 실적이 떨어짐사이트 변경 영향, 외부 사건 영향외부 반영 기록, 검색 도구의 날짜 메모

Claude Code 문서는 거부된 도구 호출에는 tool_result 이벤트가 생기지 않고, 거부 내용은 tool_decision 이벤트에만 남는다고 설명합니다. 결과 기록만 보면 동작이 시도되지 않은 것처럼 보일 수 있습니다. 작업이 멈춘 원인을 찾을 때는 결과 이벤트와 결정 이벤트를 함께 확인합니다.

같은 문서에 따르면 오류 유형은 항상 남지만, 도구 오류의 전체 메시지는 도구 상세 기록 설정을 켰을 때만 남습니다. 실무에서는 평소에는 오류 유형으로 후보를 좁히고, 재현이 필요할 때만 상세 기록을 켜서 다시 실행하는 방법을 권합니다.

민감한 내용은 어디까지 기록하나요?

도구마다 기본값이 다르므로 쓰는 도구의 설정을 먼저 확인합니다. OpenAI Agents SDK 문서는 모델 응답 생성 스팬과 함수 스팬에 입력과 출력이 저장된다고 설명합니다. 이를 제어하는 trace_include_sensitive_data의 기본값은 켜짐(True)입니다.

반대로 Claude Code 문서는 사용자 요청 원문을 기본으로 가리고, 도구 입력 세부 내용과 도구 출력 내용은 각각 별도 설정을 켜야 기록된다고 설명합니다. OpenTelemetry 규약도 시스템 지시문 기록을 사용자가 선택해서 켜는 항목(Opt-In)으로 둡니다.

실무에서는 다음 기준으로 범위를 정하는 방법을 권합니다.

  1. 고객 개인정보, 계정 정보, 미공개 계약 내용은 원문을 남기지 않고 저장 위치와 건수만 남깁니다.
  2. 지시문과 검수 기준은 원문 대신 판 번호를 남기고, 원문은 판 관리 문서에 따로 보관합니다.
  3. 상세 기록(원문 포함)은 원인 재현이 필요한 실행에만 켜고, 끝나면 끕니다.
  4. 기록을 볼 수 있는 사람의 범위를 정하고, 그 범위가 원문 접근 권한과 같은지 점검합니다.

검색 실적 변화와 작업 기록은 어떻게 연결하나요?

에이전트가 사이트를 바꾼 시점과 검색 실적이 변한 시점이 같은 화면에 있어야 둘의 관계를 검토할 수 있습니다. Google Search Central 블로그는 2025년 11월 17일 Search Console 실적 차트의 맞춤 주석 기능을 소개했습니다. 차트를 마우스 오른쪽 버튼으로 눌러 주석 추가를 고르고, 날짜를 지정해 120자까지 메모를 남기는 방식입니다.

같은 블로그 글은 주석의 쓰임으로 네 가지를 듭니다. 템플릿 업데이트·사이트 이전 같은 인프라 변경, 플러그인 추가 같은 SEO 작업, 콘텐츠 방향 변경, 휴일 같은 외부 사건입니다. 또 해당 속성에 접근할 수 있는 모든 사람이 주석을 볼 수 있으므로 민감한 개인정보를 넣지 않는 것이 좋다고 안내합니다.

실무에서는 주석에 작업 번호를 적어 작업 기록과 잇는 방법을 권합니다. 예를 들어 가상의 ○○ 기업이라면 120자 안에 들어가는 주석 문안을 다음과 같이 씁니다.

[게시] 가이드 글 3건 · 작업 W-1021-02 · 지시문 v4 · 승인 콘텐츠팀

[수정] 제품 페이지 제목 12건 변경 · 작업 W-1021-05 · 승인 웹팀

같은 기업의 작업 기록에는 같은 작업 번호로 아래 한 줄 양식을 남깁니다.

작업 W-1021-02 | 실행 3회 | 지시문 v4 | 모델 ○○(판 표기) | 입력 자료 8건 | 도구 실패 1건(수집 단계, 재시도 후 성공) | 승인 콘텐츠팀 | 원고 v3 게시 | 게시 10월 21일 14시

이렇게 연결하면 실적이 변했을 때 주석에서 작업 번호를 먼저 찾고, 그 번호로 당시 지시문 판과 도구 실패 여부를 바로 확인할 수 있습니다. 같은 날짜에 일어났다는 사실만으로 실적 변화의 원인이라고 단정하지 않고, 원인 후보 중 하나로 다룹니다.

정리

  1. 사용 중인 에이전트 도구의 기록 기본값(기록 켜짐 여부, 원문 포함 여부)을 확인하고 사내 기준에 맞게 조정합니다.
  2. 위 열 가지 항목을 열로 둔 작업 기록표를 만들고, 도구의 실행 식별자와 사내 작업 번호를 같은 행에 남깁니다.
  3. 지시문·검수 기준에 판 번호를 붙이고, 바꿀 때마다 판 번호와 변경일을 기록합니다.
  4. 사이트를 바꾸는 작업을 게시할 때마다 Search Console 실적 차트에 작업 번호가 들어간 주석을 남깁니다.
  5. 이상 신호와 원인 후보 표를 팀 문서로 공유하고, 실제로 찾은 원인을 표에 추가합니다.

참고 자료

오늘 밤부터 맡겨 보십시오

맡기실 업무와 월 처리량을 알려 주시면 구성과 요금을 함께 정리합니다.

도입 상담 신청