AI 에이전트의 가장 큰 비용 문제는 토큰입니다.
특히 출력 토큰은 입력 토큰보다 5배 비싼 모델이 있습니다(Opus 클래스). 에이전트가 긴 로그를 읽고, 장황하게 답변할 때마다 비용이 기하급수적으로 늘어납니다.
Headroom은 이 문제를 두 가지 방식으로 해결합니다.
1. 컨텍스트 압축: 도구 출력, 로그, RAG 청크를 LLM이 받기 전에 압축 2. Verbosity steering: 에이전트의 응답을 간결하게 유도해 출력 토큰 감소
두 가지 모두 프록시 기반으로, 코드 수정 없이 적용할 수 있습니다.
컨텍스트 압축: 입력 토큰 60-95% 절감
Headroom의 핵심 기능은 도구 출력과 로그를 압축하는 것입니다.
전통적인 에이전트 흐름:
도구 실행 → 전체 출력 (10,000 토큰)
↓
LLM 컨텍스트에 직접 삽입
↓
"이 로그에서 에러를 찾아줘" → 토큰 낭비
Headroom 흐름:
도구 실행 → 전체 출력 (10,000 토큰)
↓
Headroom 압축 (2,000 토큰, 80% 절감)
↓
LLM 컨텍스트에 삽입
↓
"이 로그에서 에러를 찾아줘" → 압축된 내용으로 충분
압축은 손실 없는 구조화와 의미 유지 압축을 조합합니다.
압축 대상별 효과:
├── JSON 배열/로그: 90% 압축 (반복 패턴 제거)
├── 코드 검색 결과: 21-30% 압축
├── RAG 청크: 40-60% 압축 (중복 제거)
└── 자연어 출력: 10-20% 압축 (이미 밀집됨)
압축 비용은 매우 낮습니다. 10,000 토큰 JSON의 p50 압축 시간이 0.21ms, 100,000 토큰에서도 1.4ms입니다. 에이전트 지연에 거의 영향을 주지 않습니다.
Verbosity Steering: 출력 토큰 50% 절감
입력 토큰이 문제라면, 출력 토큰은 더 큰 문제입니다. Opus 클래스 모델에서 출력 토큰은 입력의 5배 비용이 듭니다.
에이전트가 응답할 때 흔히 발생하는 낭비 패턴:
일반 응답:
"Great! Let me analyze this for you.
First, I'll look at the code structure...
[코드 블록 — 이미 컨텍스트에 있음]
Here's what I found:
- Line 42 has a null pointer issue
- Line 87 needs error handling
Let me know if you need more details!"
Headroom이 제거하는 부분:
❌ "Great! Let me analyze..." (서문)
❌ "[코드 블록 재인쇄]" (중복)
❌ "Let me know if you need..." (후문)
남는 부분:
✅ "- Line 42 has a null pointer issue"
✅ "- Line 87 needs error handling"
Headroom의 headroom learn --verbosity 명령은 과거 세션을 읽어서 사용자의 선호하는 간결성 수준을 자동으로 학습합니다.
# 과거 10개 세션 분석 → 선호도 결정
headroom learn --verbosity
# 결과: "User prefers direct answers with code references.
# No greetings, no summaries."
아키텍처: 프록시 기반 — 코드 수정 불필요
Headroom의 가장 큰 장점은 프록시 아키텍처입니다.
전통적 통합 (코드 수정 필요):
에이전트 코드 ──▶ LLM API 호출
↓ (수정 필요)
[압축 로직 삽입]
Headroom 프록시 (코드 수정 불필요):
에이전트 코드 ──▶ Headroom Proxy ──▶ LLM API
↑
투명하게 압축/변환
headroom wrap 명령으로 특정 에이전트의 프록시를 설정하면, 모든 API 호출이 Headroom을 거치면서 자동으로 압축됩니다.
# Claude Code에 Headroom 프록시 설정
headroom wrap claude-code
# Copilot CLI에 설정
headroom wrap copilot-cli
20개 이상의 에이전트를 지원합니다: Claude Code, Codex, Grok CLI, Cursor, Aider, Copilot CLI, VS Code Copilot, OpenClaw, OpenCode, Cline, Continue, Goose, OpenHands 등.
벤치마크: 압축이 정확도에 미치는 영향
Headroom의 공식 벤치마크는 압축이 정확도에 거의 영향을 주지 않음을 보여줍니다.
압축률 vs 정확도:
SQuAD v2: 19% 압축 → 97% 정확도 (베이스라인과 동일)
BFCL: 32% 압축 → 97% 정확도 (베이스라인과 동일)
TruthfulQA: ±0.03 (통계적 오차 범위 내)
GSM8K: ±0.000 (변화 없음)
결론: 20-30% 압축에서는 정확도 저하 감지 불가
실제 에이전트 작업에서의 토큰 절감 효과:
Tool search (100개 결과): 17,199 → 13,597 토큰 (21% 절감)
SRE incident debugging: 55,957 → 24,340 토큰 (57% 절감)
Codebase exploration: 58,801 → 33,895 토큰 (42% 절감)
GitHub issue triage: 46,07 → 32,429 토큰 (30% 절감)
SRE 인시던트 디버깅에서 57% 절감은 압축된 로그가 반복적인 타임스탬프와 구조를 많이 포함하기 때문입니다.
지원 API
Headroom은 주요 LLM API를 모두 지원합니다:
Anthropic: /v1/messages
OpenAI: /v1/chat/completions, /v1/responses
Gemini: chat/completions
프록시가 표준 API 엔드포인트를 가로채기 때문에, 새로운 모델이 나와도 빠르게 대응할 수 있습니다.
한계와 고려사항
- 압축률 편차: JSON과 로그는 90%까지 압축되지만, 자연어 텍스트는 10-20%만 압축됩니다. 이미 밀집된 출력은 압축 효과가 제한적입니다.
- 프록시 설정:
headroom wrap은 환경 변수나 프록시 설정을 변경합니다. 여러 에이전트를 동시에 사용할 때 충돌이 발생할 수 있습니다. - Verbosity 학습:
headroom learn은 과거 세션이 있어야 합니다. 처음 사용하는 에이전트에는 즉시 효과를 보기 어렵습니다. - 커스텀 압축 정책: 현재는 기본 압축 정책만 제공됩니다. 도메인별 커스텀 정책을 정의할 수는 없습니다.
개발자 테이크어웨이
에이전트 토큰 비용을 줄이는 가장 효과적인 방법은 두 가지입니다.
입력을 압축하세요. Headroom은 프록시 하나로 가능합니다. 코드 수정 없이 도구 출력과 로그를 압축할 수 있다면, 도입하지 않을 이유가 없습니다.
출력을 간결하게 만드세요. verbosity steering은 출력 토큰을 최대 50%까지 줄일 수 있습니다. 출력 토큰이 입력의 5배인 모델에서는 이는 곧 비용의 절반 절감을 의미합니다.
Headroom은 이 두 가지를 하나의 프록시로 해결합니다. 78k 스타는 에이전트 개발자들이 토큰 비용에 얼마나 민감한지를 보여줍니다.
에이전트를 프로덕션에 올리기 전, 토큰 비용을 먼저 계산하세요. 그리고 Headroom으로 압축을 적용하세요.