지난달 저는 하루에 약 4,000개의 요청을 처리하는 AI 에이전트에 대해 비교 테스트를 진행했습니다. 이 에이전트는 모든 호출마다 전달되는 긴 시스템 프롬프트(규칙, 도구 정의 및 예시로 구성된 약 2,800 토큰)를 가지고 있습니다. 프롬프트 캐싱을 사용하기 전에는 하루 $47이 들었습니다. 하지만 해당 시스템 프롬프트 블록에 캐싱 기능을 활성화한 후에는 하루 $6.80으로 줄었습니다.

이는 단순한 반올림 오차가 아닙니다. 단 하나의 설정 변경만으로 에이전트의 동작을 전혀 바꾸지 않으면서 비용을 85% 절감했다는 의미입니다.

프롬프트 캐싱이 정확히 어떻게 작동하는지, 그리고 함정에 빠지지 않고 어떻게 설정해야 하는지 알려드리겠습니다.

프롬프트 캐싱의 실제 작동 원리 (그리고 그렇지 않은 것)

Anthropic의 프롬프트 캐싱은 접두사(prefix) 수준에서 작동합니다. 요청을 보낼 때 API는 사용자의 메시지 중 일부가 이전에 캐시된 접두사와 정확히 일치하는지 확인합니다. 만약 일치한다면, 해당 캐시 토큰들은 전체 모델을 다시 처리하는 대신 KV 스토어(KV store)에서 제공되며, 이때 토큰당 훨씬 낮은 요율을 지불하게 됩니다.

가격 구조 (2026년 중반 Claude 3.5 Sonnet 기준):

• 일반 입력 토큰: 백만 토큰당 $3.00
• 캐시 쓰기 (최초 사용 또는 캐시 미스): 백만 토큰당 $3.75 (캐시를 작성하는 데 25%의 추가 비용 발생)
• 캐시 읽기 (캐시 히트): 백만 토큰당 $0.30 (일반 요율 대비 90% 할인)

이 캐시는 요청 간 5분 동안 유지됩니다 (각 히트마다 TTL 리셋). 따라서 5분보다 더 자주 호출되는 대부분의 프로덕션 에이전트에게는 거의 항상 이득입니다.

정확한 API 호출 방법

핵심은 cache_control 블록입니다. 캐싱을 원하는 메시지 블록 끝에

높은 ROI (투자 대비 효율) 시나리오:

1. 매 호출마다 반복되는 대규모 시스템 프롬프트 (System Prompts). 시스템 프롬프트가 1,000개 이상의 토큰이고 5분마다 한 번 이상 API를 호출한다면, 이를 캐싱하는 것이 거의 항상 순이익입니다.

2. 도구 정의 (Tool definitions). 도구 스키마 (Tool schemas)는 입력 토큰으로 계산되며, 생각보다 크기가 클 수 있습니다. 적절히 설명된 10개의 도구 세트는 800~1,200 토큰에 달할 수 있습니다. 도구 블록을 캐싱하세요.

3. 시스템 프롬프트 내의 퓨샷 예시 (Few-shot examples). 이것이 가장 중요합니다. 사람들은 출력 품질을 높이기 위해 시스템 프롬프트에 510개의 작업 예시를 추가합니다. 이러한 예시들은 2,0004,000 토큰이 될 수 있습니다. 이를 캐싱하세요.

4. 대규모 문서 분석. 동일한 문서를 두고 다양한 질문을 던지는 경우(예: 계약서에서 20개의 서로 다른 필드 추출), 문서 텍스트를 사용자 메시지 (User message)로 캐싱하고 동일한 캐시를 대상으로 20개의 쿼리를 모두 실행하세요.

낮거나 마이너스 ROI 시나리오:

• 요청 간격이 5분 이상인 경우. 캐시가 만료되면 비용을 분할 상환할 읽기 (Read) 작업 없이 매 호출마다 쓰기 프리미엄 (Write premium)만 지불하게 됩니다. 기능을 활성화하기 전에 실제 요청 주기 (Cadence)를 확인하세요.
• 매우 짧은 시스템 프롬프트 (<500 토큰). 매우 높은 볼륨이 아니라면 쓰기 프리미엄이 읽기 절감액을 초과하므로 계산상 이득이 없습니다.
• 각 프롬프트를 한 번씩만 사용하는 원샷 (One-shot) 또는 배치 (Batch) 작업. 반복되는 읽기가 없으면 이점도 없습니다.

다중 캐시 중단점 (Multiple cache breakpoints)

요청당 최대 4개의 캐시 중단점 (Cache breakpoints)을 설정할 수 있습니다. 이를 통해 프롬프트의 서로 다른 부분을 독립적으로 캐싱할 수 있습니다.

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
...

접두사 캐싱 (Prefix caching) 규칙은 엄격합니다. API는 순차적으로 마지막에 표시된 중단점까지의 모든 내용을 캐싱합니다. 만약 동적 컨텍스트 (Dynamic context)가 두 개의 캐싱된 블록 사이에 위치한다면, 두 번째 캐시 히트 (Cache hit)는 작동하지 않습니다. 접두사가 반드시 동일해야 하기 때문입니다. 항상 동적 콘텐츠를 마지막에 배치하세요.

주의해야 할 함정

공백(Whitespace)과 문자 수준의 일치 여부가 중요합니다.

캐시 키(Cache key)는 접두사(prefix)의 정확한 토큰 시퀀스(token sequence)입니다. 만약 시스템 프롬프트(system prompt)가 동적으로 생성된다면 — 예를 들어, 사용자의 이름이나 계정 등급을 프롬프트에 삽입(interpolate)하는 경우 — 각 변형은 서로 다른 토큰 시퀀스를 생성하며, 내용의 95%가 동일하더라도 캐시 히트(cache hit)가 전혀 발생하지 않습니다.

해결책: 모든 동적 콘텐츠를 마지막 캐시 중단점(cache breakpoint) 이후, 즉 맨 끝으로 이동시키세요. 캐시 블록(cached block)에는 진정으로 정적인 콘텐츠(규칙, 도구 정의, 예시 등)만 넣으십시오.

# 나쁜 예: 캐시 블록 내부의 동적 콘텐츠가 캐싱을 방해함
system = f"""
You are an agent for {company_name}.  # <-- 이 부분이 모든 요청을 고유하게 만듭니다
...

손익분기점 계산하기

캐싱을 활성화하기 전에 다음 계산을 수행해 보세요:

설정:
  T = 캐시 블록 내의 토큰 수
  R = 시간당 요청 수
...

5분 단위 윈도우(window) 내에서 1.4회 이상의 요청이 발생한다면 (이는 시간당 약 17회 요청에 해당합니다), 캐싱이 순이익(net positive)입니다. 하루 4,000회의 요청이 발생한다면, 5분 단위 윈도우마다 수백 번의 캐시 히트가 발생하게 됩니다.

작동 여부 확인하기

항상 캐시 사용량을 측정(instrument)하세요. 응답 사용량 객체(response usage object)가 정확히 어떤 일이 일어났는지 알려줍니다:

usage = response.usage
total_input = usage.input_tokens
cache_writes = getattr(usage, 'cache_creation_input_tokens', 0)
...

만약 cache_creation_input_tokens는 주로 나타나고 cache_read_input_tokens는 거의 나타나지 않는다면, 요청 주기(cadence)가 5분보다 느리거나 프롬프트가 실제로 정적이지 않은 것입니다. 캐싱 설정이 아니라 콘텐츠를 수정하세요.

결론

프롬프트 캐싱(Prompt caching)은 구현 비용은 30분 정도인데 보상은 즉각적이고 지속적인, 보기 드문 API 기능 중 하나입니다. 이는 에이전트(agent)가 수행하는 일을 바꾸지는 않지만, 동일한 작업에 대해 지불하는 비용을 바꿔줍니다.

만약 에이전트가 약 800 토큰 이상의 시스템 프롬프트를 사용하여 시간당 약 20회 이상의 호출을 수행한다면, 반드시 캐싱을 사용해야 합니다. cache_control 블록은 단 한 줄이면 충분합니다. 사용량 필드(usage fields)를 통해 작동 여부를 즉시 확인할 수 있습니다.

만약 프로덕션 규모(production scale)에서 신뢰할 수 있는 AI 에이전트(AI agents)를 구축하고 있다면, 신뢰성 패턴(reliability patterns), 비용 제어(cost controls), 그리고 테스트 전략(testing strategies)을 다루는 무료 Reliable Agent Field Guide를 확인해 보세요: penloomstudio.com/field-guide.html