Claude Agent SDK 비용 추적 — 2026년 6월 15일 전까지 해야 할 일

2026년 6월 15일, Anthropic은 Claude Agent SDK 호출, claude -p, GitHub Actions, 그리고 제3자 에이전트(third-party agents)를 구독 풀(subscription pool)에서 분리하여, 표준 API 리스트 가격으로 청구되는 별도의 달러 표시 크레딧($20 Pro, $100 Max 5x, $200 Max 20x) 체계로 전환합니다. 터미널에서의 대화형 Claude Code는 기존 위치에 유지됩니다. 프로그래밍 방식의 모든 것은 이동합니다.

따라서 다음 날 여러분의 매니저가 던질 질문은 "우리가 구독 한도 내에 있나요?"에서 "이것의 비용이 얼마인가요?"로 바뀌게 될 것입니다.

전체 가이드는 제 블로그에 있습니다: Claude Agent SDK 비용 추적: 실무 가이드 (2026). 여기는 요약 버전입니다.

SDK가 제공하는 것

모든 query() 호출은 total_cost_usd와 토큰 수를 포함하는 usage 객체가 담긴 result 메시지로 끝납니다. 또한 모델별 상세 내역도 제공되어, 동일한 호출 내에서 Opus와 Haiku에 각각 얼마가 사용되었는지 확인할 수 있습니다. TypeScript와 Python 모두 동일한 데이터를 제공하며, 필드 이름만 약간 다릅니다.

주의 사항 하나

Anthropic은 공식 문서를 통해 매우 직접적으로 경고하고 있습니다: total_cost_usd는 빌드 시점에 포함된 가격표를 기반으로 한 클라이언트 측 추정치입니다. 다음과 같은 경우 실제 청구 금액과 차이가 발생할 수 있습니다:

• 가격 정책이 변경될 때
• 설치된 SDK가 특정 모델을 인식하지 못할 때
• 클라이언트가 모델링할 수 없는 과금 규칙이 적용될 때 (6월 15일 크레딧 풀, 엔터프라이즈 할인, 서지 가격(surge pricing) 등)

예산 책정에는 SDK 수치를 사용하세요. 인보이스(invoicing) 확인을 위해서는 Usage and Cost API 또는 Console을 사용하십시오.

최소 기능 비용 로그 (Minimum Viable Cost Log)

  from claude_agent_sdk import query, ResultMessage
  import asyncio

...

시작하기에는 다섯 줄이면 충분합니다. 프로덕션 메트릭(production metrics)에 반영할 때는 사용자, 모델, 기능(feature)에 대한 태그를 추가하세요.

병렬 도구 사용 시 중복 ID 주의 사항

Claude가 한 턴 내에서 여러 도구(tools)를 병렬로 사용할 때, SDK는 동일한 id와 동일한 사용량(usage)을 공유하는 여러 개의 어시스턴트 메시지(assistant messages)를 방출합니다. 모든 어시스턴트 메시지에 걸쳐 토큰을 합산하면, 토큰을 3배 또는 4배로 중복 계산하게 됩니다.

합산하기 전에 ID로 중복을 제거하세요:

  const seenIds = new Set<string>();
  let totalInputTokens = 0;

...

또는 단순히 마지막 result 메시지에서 total_cost_usd를 읽어와 SDK가 중복 제거를 처리하도록 맡기면 됩니다.

90% 절감의 실제 원천

모든 에이전트 루프(agent loop)는 매 턴마다 동일한 시스템 프롬프트(system prompt)와 동일한 파일들을 읽습니다. SDK는 프롬프트 캐싱(prompt caching)을 자동으로 활성화합니다. 주의 깊게 살펴봐야 할 두 가지 필드는 다음과 같습니다:

• cache_creation_input_tokens — 캐시 윈도우(cache window)당 한 번, 더 높은 요율로 청구됨
• cache_read_input_tokens — 표준 입력 비용의 약 10% 수준으로 청구됨

첫 번째 턴 이후에는 캐시 읽기(cache read) 필드가 지배적이 되며 청구 금액이 완만해집니다. 15K 토큰의 시스템 프롬프트를 사용하는 Sonnet 4.6 에이전트가 20턴을 실행할 경우, 턴당 입력 비용은 약 $0.045에서 약 $0.005로 떨어집니다.

간단한 규모 산정 결정

측정된 total_cost_usd를 일주일 단위로 확인하면, 세 줄의 코드로 플랜 규모를 산정할 수 있습니다:

  Estimated monthly = weekly_total_cost_usd * 4.33

    < $20      → Pro
...

두 가지 주의 사항이 있습니다:

1. 크레딧은 이월되지 않습니다. 과다 지출이 낭비인 것과 마찬가지로, 예산 미달 지출도 실제적인 낭비입니다.
2. 폭발적인 워크로드(Bursty workloads, 예: 한 달간의 감사 작업 중 80%가 이틀 만에 발생하는 경우)는 총액이 비슷해 보이더라도 직접 API 결제(direct API billing)를 이용하는 것이 종종 더 저렴합니다.

이번 주에 해야 할 일

1. 모든 query() 호출 시 사용자(user), 모델(model), 기능(feature) 태그와 함께 total_cost_usd를 기록(Log)하세요.
2. 단계별(per-step) 합계를 신뢰하기 전에 ID를 기준으로 어시스턴트 메시지(assistant messages)의 중복을 제거(Deduplicate)하세요.
3. cache_read 대 cache_create를 그래프로 그리세요(Plot). 첫 번째 턴 이후에도 읽기(reads)가 지배적이지 않다면, 시스템 프롬프트(system prompt)나 파일이 너무 자주 변경되고 있는 것입니다.
4. 일주일 치의 콘솔(Console) 데이터를 추출하여 SDK 추정치와 비교하세요.
5. 플랜 티어(plan tier)를 선택하세요. Anthropic에서 이메일을 보내면 크레딧을 신청하세요. 초과 사용(overflow)을 대비해 사용 크레딧(usage credits)을 활성화하세요.
6. CI에서 SDK 버전을 고정(Pin)하세요. 버전 업데이트(Bumps)는 번들된 가격표를 조용히 변경합니다.

제 블로그의 전체 가이드에는 모델별 상세 분석 코드, 캐시 TTL(cache TTL) 트레이드오프, 6월 15일 이후 total_cost_usd 해석 방식의 변경 사항, 그리고 FAQ가 포함되어 있습니다: Claude Agent SDK Cost Tracking: A Practical Guide (2026).