우리 모두 그런 스크린샷을 본 적이 있을 것입니다. 누군가 에이전트(Agent)를 밤새 켜두었거나, 재시도 루프(Retry loop)가 잘못되어 예상보다 10배나 높은 청구서를 마주하게 된 상황 말이죠 — "5달러짜리 작업이 40달러가 된 상황" 같은 것 말입니다. 무서운 점은 돈 자체가 아니라, 그 무엇도 이를 막지 못했다는 사실입니다. 인보이스(Invoice)가 도착하고 나서야 알게 되니까요.

저는 가장 단순한 해결책을 원했습니다. 예산을 초과하면 다음 호출을 그냥 _차단(Block)_해버리는 하드 캡(Hard cap) 말이죠. 제가 매번 확인해야 하는 대시보드도 아니고, 직접 배포해야 하는 게이트웨이(Gateway)도 아닙니다. 그래서 저는 OpenAI/Anthropic 클라이언트(Client)에 바로 끼워 쓸 수 있는 아주 작은 래퍼(Wrapper)인 budget-guard를 만들었습니다.

3줄로 요약한 핵심 아이디어

import { guard } from 'budget-guard';

const ai = guard(openai.chat.completions, { project: 'my-app', dailyCapUSD: 50 });
...

my-app의 오늘 지출이 50달러를 넘어서면, 다음 create() 호출은 비용이 청구되기 전에 BudgetExceededError를 발생시킵니다. 통제 불능의 루프가 계좌 잔고를 바닥내기 전에 서킷 브레이커(Circuit breaker)에서 멈추게 됩니다. 이 방식은 서비스의 핵심 경로(Critical path)를 방해하지 않습니다. 호출은 여전히 제공업체(Provider)로 직접 전달되며, budget-guard는 사용량을 측정하다가 한도를 초과할 때만 작동합니다.

보너스: 돈이 어디로 갔을까?

기능별로 지출을 태깅(Tagging)하므로, 마침내 "무엇 때문에 비용이 발생했는가?"라는 질문에 답할 수 있습니다:

import { spendReport } from 'budget-guard';
spendReport('my-app'); // → { summarize: 2.41, chat: 0.88 }  (오늘 기준, USD)

OpenAI(prompt_tokens/completion_tokens)와 Anthropic(input_tokens/output_tokens)의 사용량 구조를 자동으로 감지합니다. 그 외의 경우에는 한 줄짜리 추출기(Extractor)를 전달하면 됩니다.

v0.1 버전에 대한 솔직한 고백

여러분이 인보이스에서 한계를 발견하기 전에, 제가 먼저 한계를 말씀드리는 편이 낫겠습니다:

• 프로세스당 인메모리(In-memory) 방식. 단일 스크립트, 에이전트, 또는 워커(Worker)에는 적합합니다. 여러 인스턴스를 실행하면 캡(Cap)은 인스턴스별로 적용되며 재시작 시 초기화됩니다. 공유 저장소(Redis)를 사용하는 것이 명확한 다음 단계입니다.
• 다음 호출 시 강제 적용. 아직 호출 전 토큰 추정(Token estimation) 기능은 없으므로, 서킷 브레이커가 작동하기 전에 한 번의 호출이 한도를 초과할 수 있습니다.
• 가격은 수동으로 관리되는 테이블입니다. 최신 상태를 유지할 수 있도록 PR(Pull Request)을 환영합니다.

따라서 오늘 이 도구는 1인 개발자, 사이드 프로젝트, 그리고 단일 프로세스 에이전트(single-process agents)에게 가장 적합합니다. 이들은 바로 예상치 못한 청구서를 받고 깜짝 놀랄 가능성이 가장 높은 분들이기 때문입니다.

사용해 보기 / 테스트해 보기

npm i budget-guard

MIT 라이선스, 런타임 의존성(runtime deps) 없음, TypeScript 기반. 저장소: https://github.com/kimbeomgyu/budget-guard

두 가지 사항에 대해 피드백을 받고 싶습니다. 기본적으로 차단(block)해야 할까요, 아니면 경고(warn) 후 콜백(callback)을 실행해야 할까요? 그리고 만약 플릿(fleet, 대규모 서버 군)을 운영하신다면, Redis 기반의 공유 한도(shared cap) 기능이 실제로 유용할까요, 아니면 이미 게이트웨이 계층(gateway layer)에서 이를 처리하고 계신가요? 이슈(Issues)와 PR(Pull Request)은 언제나 환영합니다.