지난 회차(제13회)에서는 AI 하네스(Harness)에 필요한 로그 항목 표를 설계했습니다. 이번에는 그것을 실제 파일로 남기기 위한 Markdown 템플릿과 JSON 스키마를 작성합니다.

"무엇을 기록할지는 결정했지만, 실제로 어떻게 파일로 출력하면 좋을까"라는 의문에 대해 구체적인 코드 예시와 함께 답하는 것이 본 기사의 목적입니다.

로그 저장 형식으로는 Markdown과 JSON을 병용하는 접근 방식을 제안합니다. 각각의 역할은 다음과 같습니다.

SE 업무에 비유하자면, Markdown은 "장애 보고서", JSON은 "로그 DB의 레코드"에 해당합니다. 동일한 실행 데이터를 서로 다른 뷰(View)로 볼 수 있게 함으로써 운영의 유연성을 크게 향상시킬 수 있습니다.

다음은 AI 에이전트 실행 로그의 Markdown 템플릿입니다.

# AI 에이전트 실행 로그
## 기본 정보
| 항목 | 값 |
...

기본 정보를 표 형식으로 정리: 일람성 확보 -
프롬프트(Prompt)와 응답(Response)을 분리: 입출력 대응을 명확하게 -
컨텍스트(Context) 정보 포함: RAG에서 무엇을 참조했는지에 대한 추적성 -
도구 호출(Tool Call) 기록: MCP 도구의 이용 이력

다음은 동일한 실행 데이터를 JSON으로 표현한 스키마입니다.

{
"execution_id": "exec_20240101_001",
"timestamp": {
...

플랫(Flat) 구조보다 중첩(Nested) 구조: timestamp.start와 timestamp.end와 같이 관련 항목을 그룹화 -
배열(Array)로 가변 길이 데이터 대응: context나 tool_calls는 배열로 여러 건에 대응 -
metadata로 확장성 확보: 나중에 항목을 추가하기 쉬운 설계

다음은 Markdown과 JSON을 모두 출력하는 Python 코드 예시를 보여줍니다.

import json
from datetime import datetime
from pathlib import Path
...

dataclass로 데이터 구조를 명확화: 로그 항목의 스키마를 타입(Type)으로 표현 -
to_json과 to_markdown 분리: 용도에 따른 출력 형식 전환 -
save_log로 양쪽 동시 저장: 저장 누락 방지

이 코드는 그대로 자신의 프로젝트에 복사하여 사용할 수 있습니다.

로그 파일 배치에 대해 다음과 같은 구성을 제안합니다.

logs/
├── 2024-01/
│ ├── exec_20240101_001.json
...

운용 시나리오별 사용법을 정리합니다.

AI 에이전트의 로그는 기존 시스템의 로그보다 크기가 커지기 쉽습니다 (프롬프트와 응답의 전문을 포함하기 때문). 로테이션(Rotation)의 판단 기준을 제시합니다.

이것도 기존 시스템의 로그 로테이션과 같은 생각입니다. 당신의 경험이 그대로 활용됩니다.

프롬프트나 응답에 기밀 정보가 포함되는 경우, 로그에 그대로 기록하면 보안 리스크가 됩니다. 제19회에서 자세히 다루겠지만, 현 시점에서는 "기밀 정보를 마스킹(Masking)한 후 로그에 기록한다"라는 원칙을 의식해 주세요.

프롬프트와 응답의 전문을 포함하면 로그 파일이 커지기 쉽습니다. INFO 레벨에서는 프롬프트의 앞 200자(Character)와 토큰(Token) 수만을 기록하는 등, 레벨에 따른 정보량 제어가 중요합니다.

기존의 로그 운용 경험으로부터 다음과 같은 고안을 할 수 있습니다.

• 알림 설정 (Alert Setting): 토큰 소비가 임계값을 초과하면 알림 (모니터링 시스템과 동일)

• 대시보드 (Dashboard): JSON 로그를 집계하여 일일 보고서 생성 (BI 도구 경험 활용)

• 로그 상관 분석 (Log Correlation Analysis): 여러 로그를 대조하여 문제 패턴 발견 (장애 분석 기술)

• Markdown은 사람이 읽기 위한 용도, JSON은 프로그램이 처리하기 위한 용도로 병용

• dataclass로 로그 스키마 (Schema)를 정의하고, 두 형식으로 변환하는 구현이 심플함

• 파일 구성, 로테이션 (Rotation), 보안은 기존 시스템의 지식을 그대로 활용

• 우선 작게 시작하여, 운용하면서 확장

제15회에서는, AI 에이전트의 워크플로우에 인간의 승인 지점 (Human-in-the-loop)을 어디에 배치할 것인가를 설계합니다.

구체적으로는 다음과 같은 내용을 다룹니다.

• AI 에이전트 처리 플로우에서의 승인 지점 배치 기준
• 리스크 레벨에 따른 승인 입도 (Granularity) 설계
• 이번에 작성한 로그와 승인 플로우의 연계
• 승인 플로우의 구현 패턴

"로그로 기록할 뿐만 아니라, 중요한 처리 전에 사람이 체크하는 메커니즘이 있다면 훨씬 안심할 수 있을 텐데"라는 생각에 답하는 회차입니다. 꼭 기대해 주세요.

연재: AI에게 일자리를 빼앗길 불안으로부터 시작하는 하네스 작성 입문

다음 회 (제15회): Human-in-the-loop은 어디에 넣어야 하는가