Transcript Hygiene: Provider별 제약 조건을 해결하는 데이터 정제 기술

LLM을 연동하다 보면 Provider마다 요구하는 데이터 포맷이 미묘하게 달라서 고생할 때가 많죠. 어떤 곳은 Tool Call ID 형식이 너무 엄격하고, 어떤 곳은 User와 Assistant의 대화 순서가 반드시 교차해야만 합니다. 이런 제약 조건을 일일이 맞추지 않으면 API 호출이 실패하거나 예기치 않은 오류가 발생하게 돼요.

이 문서는 모델 컨텍스트를 빌드하기 전, 메모리 상에서 트랜스크립트를 Provider의 요구사항에 맞게 자동으로 조정하는 Provider Fixups 과정을 다룹니다. 이 과정은 디스크에 저장된 JSONL 파일을 직접 수정하지 않고, 실행 시점에만 적용되는 안전한 방식입니다.

필요한 것

• src/agents/transcript-policy.ts (정책 선택 로직)
• src/agents/pi-embedded-runner/google.ts (Sanitization 적용 로직)
• src/agents/session-file-repair.ts (세션 파일 복구 로직)
• src/agents/pi-embedded-helpers/images.ts (이미지 처리 로직)

빠른 시작

트랜스크립트 정제는 임베디드 러너(Embedded Runner)에서 중앙 집중식으로 관리됩니다. 5분 안에 파악하는 핵심 흐름은 다음과 같아요.

1. 정책 결정: src/agents/transcript-policy.ts에서 provider, modelApi, modelId를 기반으로 어떤 규칙을 적용할지 결정합니다.
2. Sanitization 적용: google.ts 파일의 sanitizeSessionHistory 함수가 실제 수정 작업을 수행합니다.
3. 글로벌 규칙 실행: 이미지 크기 조정 및 잘못된 Tool Call 제거와 같은 공통 규칙이 먼저 적용됩니다.
4. Provider별 특화 수정: 각 모델의 API 특성에 맞춰 ID를 수정하거나 대화 순서를 조정합니다.

Global Rules

모든 Provider에 공통으로 적용되는 두 가지 핵심 규칙입니다.

1. 이미지 Sanitization

이미지 페이로드가 너무 크면 Provider가 거절할 수 있어요. 이를 방지하기 위해 Base64 이미지의 크기를 줄이거나 다시 압축합니다.

• 적용 위치: src/agents/pi-embedded-helpers/images.ts의 sanitizeSessionMessagesImages

2. 잘못된 Tool Call 제거

input이나 arguments가 없는 Assistant의 Tool Call 블록은 모델 컨텍스트를 구성하기 전에 삭제합니다. Rate limit 오류 등으로 인해 불완전하게 저장된 데이터를 걸러내기 위함이에요.

• 적용 위치: src/agents/session-transcript-repair.ts의 sanitizeToolCallInputs

Provider Matrix

현재 각 Provider별로 적용되는 구체적인 동작 방식입니다.

• OpenAI / OpenAI Codex
  • 이미지 Sanitization만 적용합니다.
  • 모델 전환 시, 뒤따르는 내용이 없는 고립된 reasoning signature를 삭제합니다.
• Google (Gemini / Antigravity)
  • Tool call id를 엄격한 영문 숫자로 제한합니다.
  • 대화 순서가 Assistant로 시작할 경우 앞에 작은 User bootstrap 데이터를 추가합니다.
  • Gemini 스타일의 대화 순서 교차(Turn alternation)를 강제합니다.
  • Antigravity Claude의 경우 thinking signature를 정규화합니다.
• Anthropic / Minimax
  • 연속된 User turn을 하나로 합쳐서 엄격한 순서 교차 조건을 충족합니다.
  • Tool result pairing 복구 및 가공된(Synthetic) Tool result를 생성합니다.
• Mistral
  • Tool call id를 9자리 영문 숫자로 제한(strict9)합니다.
• OpenRouter Gemini
  • Base64 형식이 아닌 thought_signature 값을 제거합니다.

문제 해결

세션 로드 전 파일 복구

트랜스크립트 하이진은 메모리에서 작동하지만, JSONL 파일 자체가 손상된 경우에는 로드 전에 복구가 필요합니다. src/agents/session-file-repair.ts의 repairSessionFileIfNeeded가 이 역할을 수행하며, 잘못된 라인을 삭제하고 원본 파일은 백업해 둡니다.

OpenAI에서 Tool Call ID 문제

2026.1.22 업데이트 이후 OpenAI는 이미지 Sanitization 외에 트랜스크립트를 거의 건드리지 않는 ‘No-touch’ 원칙을 유지합니다. 만약 call_id 페어링 문제가 발생한다면 Runner의 정책 로직을 확인해 보세요.

AI Setup Assistant

다음 단계

• /reference/session-management-compaction