비용, 지연, 신뢰성을 예산 안에서 관리하기

개발 중에는 호출을 몇 번 실행해 보는 정도라 청구서를 만날 일이 없습니다. 프로덕션에서는 같은 호출이 대량으로 실행되고, 비용과 지연이 시스템의 제약 조건이 됩니다. Claude 시스템의 관측이란 호출마다 세 가지 지표를 기록하는 일입니다 — 토큰 사용량(입력·출력), 지연, 에러율.

세 지표가 호출마다 남으면, 월 청구서 총액을 놓고 짐작하는 대신 어느 단계가 비싸고 어느 단계가 느린지 바로 확인할 수 있습니다. 계측은 처음부터 모든 호출에 붙여 두는 것이 좋습니다. 나중 일로 미루면, 비용이 왜 이렇게 나왔는지 확인하기도 전에 청구서부터 받게 되는 경우가 많습니다. 코드로는 API가 이미 반환하는 사용량을 기록하는 얇은 래퍼 하나면 됩니다.

THREE METRICS PER CALL — 계측 래퍼

import time

def instrumented_call(make_call, step_name):
    start = time.perf_counter()
    resp = make_call()  # raises on any API error
    latency_ms = (time.perf_counter() - start) * 1000
    log_metric(step=step_name,
        input_tokens=resp.usage.input_tokens,
        output_tokens=resp.usage.output_tokens,
        latency_ms=latency_ms)
    return resp

호출 단위 계측이 만드는 차이는, 던질 수 있는 질문이 달라진다는 데 있습니다. 기록 없이 비용이 튀면 물을 수 있는 질문은 "왜 청구액이 높지?" 하나뿐입니다. 호출 단위 기록이 있으면 어떤 요청 유형의 어떤 단계가 원인인지 물을 수 있고, 답도 기록에서 바로 꺼낼 수 있습니다.

전체가 고르게 비싸 보이던 흐름도 들여다보면 한 단계가 지출의 90%를 차지하는 경우가 많고, 최적화는 그 단계에 집중하는 것이 효율적입니다. 지연도 마찬가지입니다. 느린 단계는 예상했던 곳이 아닌 경우가 많아서, 트레이스요청이 거쳐 간 단계를 순서대로 따라가며 남긴 기록.와 호출별 시간 기록이 있어야 엉뚱한 곳을 최적화하는 일을 피할 수 있습니다.

비용이나 지연 문제는 대부분 측정 가능한 몇 가지 요소 중 하나로 좁혀집니다. 어느 레버가 문제인지 먼저 확인해 두면, 최적화가 짐작이 아니라 측정에서 출발하게 됩니다.

COST LEVERS — 레버별 비용·지연 영향

다섯 번째 레버인 스트리밍 + 도구 사용은 따로 볼 필요가 있습니다. 스트리밍이 아닌 호출에서는 응답 전체가 객체 하나로 도착해 tool_use 블록을 바로 읽을 수 있습니다. 스트리밍 호출에서는 응답이 서버 전송 이벤트의 연속으로 도착하고, tool_use 블록이 여러 delta 이벤트에 걸쳐 조금씩 쌓인 뒤에야 완성됩니다. 이 점을 계산에 넣지 않고 스트림을 소비하면, 도구 입력이 불완전한 채로 넘어가 다음 단계에서 겉으로 잘 드러나지 않는 실패가 생깁니다.

패턴은 이렇습니다. 스트림이 닫힐 때까지 인덱스별로 delta를 쌓아 두고, 닫힌 뒤에 완성된 블록에서 도구 호출을 복원합니다.

STREAMING WITH TOOL USE — delta 누적 후 복원

def stream_with_tools(client, **kwargs):
    tool_blocks = {}  # index -> accumulated block
    text_chunks = []

    with client.messages.stream(**kwargs) as stream:
        for event in stream:
            if event.type == "content_block_start":
                block = event.content_block
                tool_blocks[event.index] = {
                    "type": block.type,
                    "id": getattr(block, "id", None),
                    "name": getattr(block, "name", None),
                    "input_json": ""
                }
            elif event.type == "content_block_delta":
                delta = event.delta
                if delta.type == "input_json_delta":
                    tool_blocks[event.index]["input_json"] += delta.partial_json
                elif delta.type == "text_delta":
                    text_chunks.append(delta.text)
            elif event.type == "message_stop":
                break

    # reconstruct completed tool calls after stream closes
    tool_calls = []
    for block in tool_blocks.values():
        if block["type"] == "tool_use":
            tool_calls.append({
                "id": block["id"],
                "name": block["name"],
                "input": json.loads(block["input_json"])
            })

    return "".join(text_chunks), tool_calls

tool_use 블록은 스트림이 닫히고 input_json이 전부 쌓인 뒤에야 실행에 써도 안전합니다. 부분 블록으로 실행하면 도구 입력이 잘못 만들어집니다. 실패 처리 레슨에서 본 '재시도 가능 vs 종료' 구분이 여기에도 그대로 적용됩니다. 응답 중간에 끊긴 스트림은 일시적 실패이므로, 부분 출력을 다음 단계로 넘기는 대신 요청 전체를 다시 시도합니다.

모델은 무언가를 생성하기 전에 먼저 입력을 처리합니다. 프롬프트를 토큰으로 나누고, 그 내용을 읽는 데 필요한 내부 표현을 만듭니다. 보통의 요청에서는 이 처리 작업이 응답과 함께 버려집니다. 다음 요청이 같은 내용을 반복하면 같은 처리를 처음부터 다시 합니다. 이 반복 작업을 없애는 레버가 프롬프트 캐싱입니다.

프롬프트 캐싱은 표시해 둔 지점까지의 처리 작업을 저장해 두고, 이후 요청이 같은 내용을 그 지점까지 보내면 다시 계산하는 대신 읽어 오게 합니다. 첫 요청이 캐시에 쓰고, 후속 요청이 캐시에서 읽는 구조입니다. 캐시 쓰기는 기본 입력 토큰보다 비쌉니다 — 5분 TTL은 1.25배, 1시간 TTL은 2배. 대신 캐시 읽기는 기본 입력의 0.1배입니다. 그래서 읽기가 쓰기보다 많을 때만 계산이 맞습니다. 캐싱이 안정적이고 자주 재사용되는 접두부prefix — 요청 맨 앞에서 반복되는 구간. 캐시는 이 앞부분이 정확히 같을 때만 적중한다.에 맞는 이유도 여기에 있습니다. 같은 캐시를 읽는 요청이 많아질수록 전체 비용과 지연이 함께 내려갑니다.

설정 방법은 두 가지입니다. 자동 모드에서는 요청 최상위에 캐시 플래그 하나만 켜면, 대화가 길어지는 동안 시스템이 캐시 지점을 관리해 줍니다. 대부분의 경우 여기서 시작하는 것이 좋습니다. 명시적 방식에서는 특정 콘텐츠 블록에 cache_control 마커를 두고, 그 지점까지의 작업이 캐시됩니다. 어느 쪽이든 마지막 캐시 지점 이후의 내용은 평소처럼 처리됩니다. 캐싱할 가치가 가장 큰 것은 요청 사이에 바뀌지 않는 부분입니다. 긴 시스템 프롬프트와 큰 도구 스키마가 대표적인 후보입니다. 이 둘은 거의 바뀌지 않는 반면, 사용자 메시지는 턴마다 바뀌기 때문입니다.

어떤 작업에서 캐싱이 이득이 되는지는 세 가지 조건이 정합니다.

• 1캐시된 내용이 완전히 같아야 합니다. 캐시는 정확한 접두부 일치로 판정합니다. 캐시 지점 앞에서 "please" 같은 단어 하나만 더해져도 캐시가 무효가 되고 전체를 다시 처리합니다. 그래서 캐싱은 안정된 내용에 맞고, 실시간 상태를 반영해야 하는 내용과는 맞지 않습니다. 요청마다 바뀌는 내용은 캐시에 적중할 일이 없습니다.
• 2같은 내용이 곧 다시 와야 합니다. 기본 캐시 수명은 5분이고, 적중할 때마다 연장됩니다. 1시간짜리 수명은 추가 비용을 내고 쓸 수 있습니다. 같은 접두부가 그 시간 안에 다시 와야 절약이 성립합니다. 1분에 몇 번씩 재사용되는 접두부는 이득이지만, 1시간에 한 번 재사용되는 접두부는 기본 수명으로는 다음 요청이 오기 전에 캐시가 만료되어 이득이 없습니다.
• 3캐시할 접두부가 최소 길이를 넘어야 합니다. 캐싱에는 모델별로 다른 최소 길이 기준이 있습니다. 짧은 프롬프트는 아무리 안정적이어도 이득이 없습니다. 접두부가 길고 안정적일수록 재사용되는 처리 작업이 커집니다. 길고 고정된 시스템 프롬프트를 쓰는 대량 호출 시스템에서 캐싱이 가장 효과적인 이유입니다.

절약과 맞바꾸는 조건이 하나 있습니다. 캐싱은 캐시된 내용이 나중 요청에서도 여전히 맞다고 가정합니다. 접두부가 변할 수 있는 데이터를 반영해야 한다면, 캐시가 살아 있는 동안 오래된 버전이 쓰일 수 있습니다. 이 시간 차를 감당할 수 있는 작업인지 먼저 확인해 볼 필요가 있습니다. 고정된 시스템 프롬프트와 안정된 도구 스키마는 낡을 것이 없어서, 캐싱하기에 안전하면서 절약 효과도 큰 자리입니다.

어떤 작업은 답을 지금 받을 필요가 없습니다. 밤사이 처리하는 분류 작업, 대량 데이터 백필backfill — 쌓여 있던 과거 데이터를 한꺼번에 다시 처리해 채워 넣는 작업., 정기 리포트는 모두 기다릴 수 있는 일입니다. 이런 작업을 위해 Message Batches API는 요청을 모아 비동기로 처리하고, 그 대신 같은 호출을 하나씩 보낼 때보다 요청당 비용을 낮춥니다.

할인 폭은 급하지 않은 대량 작업이라면 선택을 좌우할 만큼 큽니다. 정확한 할인율은 시점에 따라 달라질 수 있어, 원문 코스도 구현 시점에 기준 문서에서 확인하도록 안내합니다.

내주는 것은 지연입니다. 배치를 제출하면 결과는 즉시가 아니라 비동기 완료 시한 안에 돌아옵니다. 그래서 배치는 사용자가 기다리고 있는 요청에는 맞지 않고, 일정이 이끄는 작업에는 맞습니다. 스트리밍과 정확히 반대 방향의 결정인 셈입니다. 스트리밍은 사용자가 보고 있는 응답 하나가 얼마나 빠르게 느껴지는지를 최적화하고, 배치는 기다리는 사용자가 없는 작업의 비용을 최적화합니다. 요청 하나는 사용자 대면이거나 아니거나 둘 중 하나라서, 두 레버가 같은 요청을 두고 경쟁할 일은 없습니다.

배치와 프롬프트 캐싱은 급하지 않은 작업이 같은 컨텍스트를 여러 요청에서 재사용할 때 겹쳐 쓸 수 있습니다. 배치 할인이 요청 각각의 비용을 낮추고, 캐싱이 요청 안에서 반복되는 접두부의 비용을 낮춥니다. 길고 고정된 시스템 프롬프트를 쓰는 정기 작업이라면 둘 다에서 이득을 봅니다. 이 조합을 알아보는 것이 이 레슨 끝의 점검 과제이기도 합니다.

오케스트레이터-워커 패턴에서는 리드 에이전트가 과제를 하위 작업으로 나눠, 각자 자기 컨텍스트 윈도를 가진 여러 서브에이전트에게 맡깁니다. 서브에이전트들이 병렬로 작업을 마치면 리드가 결과를 모아 합칩니다. 코드로 보면 계획, 병렬 분배, 종합의 세 단계입니다.

ORCHESTRATOR-WORKER — 계획 · 병렬 분배 · 종합

async def orchestrate(task):
    plan = await lead.plan(task)        # lead agent decomposes
    results = await gather(*[           # subagents run in parallel
        worker.run(subtask) for subtask in plan.subtasks
    ])                                    # each spends its own tokens
    return await lead.synthesize(results)  # lead compiles the answer

이 패턴은 독립된 부분으로 나눌 수 있는 큰 과제에 실제로 도움이 됩니다. 여러 출처를 찾아보는 리서치가 대표적입니다. 서브에이전트들이 하나씩 차례로가 아니라 동시에 탐색할 수 있기 때문입니다.

Anthropic의 리서치 시스템이 실제로 이 패턴을 쓰고, 트레이드오프를 수치로 보고한 적이 있습니다. 내부 리서치 평가에서 Claude Opus 4를 리드로, Claude Sonnet 4를 서브에이전트로 쓴 멀티에이전트 구성은 단일 Claude Opus 4 기준선 대비 큰 폭의 개선을 보였습니다. 대신 비용은 보통 채팅의 약 15배 토큰입니다. 서브에이전트마다 자기 컨텍스트에 자기 토큰을 쓰기 때문입니다.

반대로 코딩처럼 단계가 서로 얽힌 과제에는 효과가 떨어집니다. 각 단계가 이전 결과에 기대고 있어 병렬로 탐색할 수 없기 때문입니다. Anthropic의 분석에서는 성능 차이의 대부분이 토큰 사용량으로 설명됐습니다. 이 아키텍처의 개선은 결국 병렬 연산을 늘린 데서 나온다는 해석입니다.

그래서 과제가 정말로 병렬 탐색을 필요로 할 때만 쓰는 것이 좋습니다. 대부분의 일은 컨텍스트를 잘 갖춘 단일 에이전트가 훨씬 낮은 비용으로 처리합니다. 배수는 무언가 잘못됐을 때 더 커지기도 합니다. 통제를 벗어난 서브에이전트 하나, 지나치게 큰 도구 결과 하나가 요청이 끝나기 전에 15배 기준선을 훌쩍 넘길 수 있습니다.

대략적인 비용 추정으로 트레이드오프를 구체적으로 확인해 보겠습니다. 단일 에이전트가 리서치 질문 하나에 약 1만 토큰을 쓴다고 해 봅니다. 오케스트레이터-워커 버전은 리드 하나와 서브에이전트 넷을 띄우고, 각자 자기 컨텍스트에서 자기 몫의 출처를 읽습니다. 마지막에 리드가 결과를 종합합니다. Anthropic의 보고 기준으로 다섯 개의 컨텍스트에 종합 단계까지 더하면 15배 — 같은 질문이 15만 토큰 규모가 됩니다.

그 질문이 사실 리서치처럼 보이는 단건 조회였다면, 배수를 그대로 내고 얻은 것이 없는 상태가 됩니다. 다섯 컨텍스트 중 넷이 과제에 필요 없던 일을 한 것이기 때문입니다. 15만이라는 숫자 자체는 크지도 작지도 않습니다. 과제가 추가 에이전트를 정말 필요로 했는지에 따라 가치가 정해집니다.

비용 추정에 잡히지 않는 통제 차원도 있습니다. 작업을 여러 에이전트로 나누면 실패가 생길 수 있는 지점도 같이 늘어납니다. 서브에이전트마다 실패 처리 레슨의 '재시도 가능 vs 종료' 구분, 백오프backoff — 재시도 사이의 대기 시간을 점점 늘려 가며 기다리는 방식., 폴백을 각각 따로 갖춰야 합니다. 백오프 없이 레이트 리밋rate limit — 일정 시간 동안 허용되는 요청 수의 상한. 넘으면 요청이 거부된다.에 걸린 서브에이전트 하나 때문에, 리드가 돌아오지 않는 결과를 기다리며 종합 단계 전체가 멈출 수 있습니다. 오케스트레이션은 실패 처리 작업을 대신해 주는 것이 아니라 몇 배로 늘립니다. 병렬 탐색이 그만한 관리 부담을 감수할 가치가 있을 때만 쓰는 것이 좋은 이유가 하나 더 생기는 셈입니다. 모델 선택도 여기서 도움이 됩니다. 리드에는 더 유능한 모델을, 서브에이전트에는 더 저렴한 모델을 쓰면, 모든 병렬 컨텍스트에 최상위 요금을 내지 않으면서 조정 품질은 필요한 자리에 유지할 수 있습니다.

비용은 예산의 절반일 뿐입니다. 나머지 절반은 신뢰성이고, 신뢰성이 곧 비용이 그 아래로 내려가면 안 되는 기준선이 됩니다. 가장 싼 구성이 가장 신뢰할 만한 구성인 경우는 드뭅니다.

재시도 예산과 지연 상한 같은 기준선을 먼저 정하고, 비용은 그 위에서 조절하는 순서가 좋습니다. 신뢰성 하한선 아래로 비용을 깎으면, 눈에 보이던 지출이 겉으로 드러나지 않는 실패로 바뀝니다. 프로덕션에서는 대체로 더 나쁜 교환입니다. 조금 높아진 청구서는 설명할 수 있지만, 동작하지 않는 시스템은 설명하기 어렵기 때문입니다.

하한선을 구체적인 수치로 정해 보면 이 원칙이 분명해집니다. 사용자 대면 요청은 4초 안에 완료되어야 하고, 실패한 의존성은 최대 3회까지 재시도할 수 있다고 정했다고 해 봅니다. 이 제약이 하한선입니다. 이제 모든 비용 최적화가 이 조건을 만족해야 합니다. 더 작고 싼 모델로 바꾸는 것은, 지연 상한 안에 들어오고 에러율이 재시도 예산을 소진할 만큼 오르지 않는다면 괜찮습니다. 느린 의존성의 재시도 횟수를 2회로 줄여 비용을 아끼는 것은, 실패율이 하한선이 허용하는 수준을 넘는다면 받아들이기 어렵습니다. 비용을 낮추는 대신 실패한 요청을 늘리는 교환이기 때문입니다.

하한선이 있으면 비용을 아끼는 변경마다 신뢰성을 모르는 사이에 내주지 않았는지 확인하는 단계가 생깁니다. 절약이 아무리 매력적으로 보여도 그 아래로는 깎지 않는 경계가 분명해지는 효과도 있습니다.

순서가 중요한 이유는, 비용과 신뢰성이 반대 방향으로 압력을 만드는데 비용 쪽이 대개 더 눈에 띄기 때문입니다. 높은 청구액은 매일 대시보드에 표시되어 줄이라는 압력을 계속 만듭니다. 신뢰성 문제는 가끔 나오는 실패라 잡음으로 넘기기 쉽고, 쌓여서 장애가 된 뒤에야 심각성이 드러납니다. 비용을 먼저 최적화하고 신뢰성을 나중에 보면 더 눈에 띄는 쪽이 이기게 되고, 하한선은 이미 넘어선 뒤에야 발견되는 경우가 많습니다. 하한선을 먼저 정하면 순서가 뒤집힙니다. 신뢰성이 고정된 제약이 되고, 비용이 그 아래에서 최적화하는 대상이 됩니다. 앞 섹션에서 만든 평가 세트가 이 하한선을 점검 가능한 형태로 만들어 줍니다. 고정해 둔 기준 점수가 허용할 수 있는 최소 신뢰성을 확인 가능한 형태로 정의하므로, 비용을 아끼는 변경이 점수를 기준 아래로 떨어뜨리면 배포 전에 게이트에서 걸립니다.

OBSERVABILITY & ORCHESTRATION — 만들면서 열어 두는 참조표

작업이 느려서, 동시에 처리하면 더 빨리 끝나리라는 계산으로 여러 서브에이전트에 병렬로 나눴다고 해 봅니다. 지연은 조금 줄었습니다. 그런데 청구서는 단일 에이전트 버전의 몇 배로 도착했고, 답의 품질은 거의 그대로였습니다.

한 개발자가 내부 채널에 올린 질문과, 시니어 개발자의 답변입니다.

개발자는 과제를 단일 에이전트로 되돌리고 컨텍스트는 그대로 유지했습니다. 청구액이 내려갔고 답의 품질은 유지됐습니다. 오케스트레이션이 나쁘다는 결론이 아닙니다. 토큰을 몇 배 더 쓰는 선택은, 작업을 정말로 병렬로 나눌 수 있을 때만 그만한 값어치를 합니다.

원문의 점검 과제는 상황 네 개에 구성 스니펫 A–D를 짝지어 고르는 형식입니다. 여기서는 상황별 객관식으로 옮겼습니다. 스니펫마다 에이전트 유형과 주된 비용 레버가 주석으로 붙어 있습니다. 정답을 먼저 떠올려 본 뒤 골라 보세요. 맞히면 설명이 나옵니다.

LABELED SNIPPETS — 구성 스니펫 A–D

A  orchestrator_worker(lead=LARGE, workers=SMALL, n=5)   # lever: parallel split
B  single_agent(model=SMALL, batch=True, cache=True)     # lever: Message Batches API
   # (~50% cost reduction) + prompt caching
C  single_agent(model=SMALL, retrieval="fetch_once")     # lever: model choice
D  single_agent(model=SMALL, stream=True)                # lever: streaming