Anthropic 0.105.0 심층 분석: 출력 귀속과 파일 용량 제한

v0.105.0에 포함된 것들

Anthropic SDK v0.105.0은 2026년 5월 28일 Claude Opus 4.8 모델 출시와 함께 배포된 4가지 신기능 릴리스입니다 . 추가된 네 가지는 다음과 같습니다: claude-opus-4-8 모델 식별자, 대화 중간 시스템 블록 주입, usage.output_tokens_details 어트리뷰션 필드, 그리고 클라이언트별로 설정 가능한 파일 업로드 크기 제한입니다. 이후 24시간 이내에 두 개의 패치 릴리스가 뒤따랐습니다—v0.105.1(Trusted Publishing을 통한 공급망 강화)과 v0.105.2(미문서화 범위)—로 인해 패키지를 추적하는 SDK 사용자들에게 밀도 높은 이틀간의 업데이트 구간이 되었습니다.

라이브러리와 모델은 의도적으로 함께 배포됩니다: claude-opus-4-8을 호출하려면 최소 anthropic==0.105.0이 필요합니다 . 이러한 페어링은 Anthropic이 이전 Opus 티어 출시를 처리해 온 방식과 일치합니다—SDK 업데이트와 모델 가용 날짜가 동기화되어 모델 문자열이 공개 당일 바로 사용 가능해집니다.

코드베이스 검색이 필요한 정리 변경 사항이 하나 있습니다: managed-agents 모듈의 예제 스크립트가 private-sandbox-worker에서 self-hosted-sandbox-worker로 이름이 변경되었으며, 이는 2026년 5월 19일 v0.103.0에서 도입된 용어와 일치합니다 . 이름 변경만 있을 뿐 동작 차이는 없지만, 이전 스크립트 이름을 참조하는 CI 파이프라인이나 Makefile은 업그레이드 시 소리 없이 중단될 수 있습니다.

출력 사용량 가시성: 새로운 세분화 필드

usage.output_tokens_details 필드는 Messages API 응답의 새로운 중첩 객체로, 유형별 출력 토큰 소비를 세분화하며, cache_read_input_tokens와 cache_write_input_tokens를 노출하는 기존 usage.input_tokens_details 구조를 그대로 반영합니다 . 이 필드가 없었을 때는 추론 체인에서 생성된 토큰이든 최종 텍스트 응답에서 생성된 토큰이든 모든 출력 토큰이 usage.output_tokens에 단일 불투명 정수로 표시되었습니다. 확장 사고를 활성화하는 파이프라인에서 이 불투명성은 비용 추적의 실질적인 공백이었습니다.

예상되는 세분화는 추론(사고) 토큰을 표준 출력 토큰과 분리합니다. 확장 사고는 응답을 생성하기 전에 모델의 내부 연쇄 추론을 실행합니다. 이 추론 토큰은 텍스트 출력 토큰과 동일하게 청구되지만 질적으로 다른 예산 항목을 나타냅니다. output_tokens_details를 통해 대용량 파이프라인을 운영하는 팀은 이제 수동 계측이나 대리 지표 없이 "월간 출력 지출 중 추론 오버헤드가 얼마나 되는가?"에 답할 수 있습니다.

"Claude Opus 4.8은 더 예리한 판단력, 진행 상황에 대한 솔직함, 그리고 이전 모델보다 더 오래 독립적으로 작업할 수 있는 능력을 갖추고 있습니다." — Anthropic, Claude Opus 4.8 출시 포스트

입력 측과의 대칭은 의도적입니다. usage.input_tokens_details는 프롬프트 캐싱을 얼마나 효과적으로 사용하고 있는지 추적할 수 있게 해줍니다—cache_read_input_tokens가 낮으면 반복되는 프리픽스 토큰에 전액을 지불하고 있는 것입니다. 출력 측 아날로그는 이 루프를 완성합니다: 청구에 영향을 미치는 모든 토큰 클래스는 이제 집계 합계에서 추론할 필요 없이 전용 필드를 갖게 됩니다. 확장 사고와 표준 완성을 혼합하는 대용량 에이전트 워크플로우가 가장 큰 실질적 혜택을 누릴 것입니다.

중요한 주의 사항이 있습니다: v0.105.0 기준으로 output_tokens_details 내의 정확한 하위 필드 이름은 아직 공식 API 레퍼런스에 포함되지 않았습니다 . 필드 존재 여부는 응답 유형에 따라 달라지기도 합니다—확장 사고가 비활성화된 경우 추론 관련 하위 필드가 없거나 0일 수 있으며 존재가 보장되지 않습니다. 안전한 통합 패턴: 테스트 환경에서 원시 response.usage 객체를 검사하고, 방어적 접근을 위해 getattr(response.usage, "output_tokens_details", None)을 사용하며, 스키마 확정을 위해 SDK CHANGELOG를 모니터링하세요. 공식 문서에 등장하기 전까지는 프로덕션 코드에 하위 필드 이름을 하드코딩하지 마세요.

LangSmith, OpenTelemetry 또는 자체 미들웨어로 이미 사용량 지표를 로깅하는 팀이라면 output_tokens_details 추출 추가는 기존 계측 훅에 한 줄만 추가하면 됩니다. 요청마다 추론 깊이가 달라지는 워크로드에서 가장 큰 효과를 발휘합니다—빠른 검색 호출과 깊은 다단계 계획이 혼합된 큐는 세분화를 로깅하기 시작하면 추론 대 텍스트 비율에서 의미 있는 차이를 보여줄 것입니다.

파일 업로드 크기 제한 설정하기

PR #1825는 SDK의 기본 파일 업로드 최대 크기를 재정의할 수 있는 설정 옵션을 추가합니다 . 이 제한은 클라이언트 인스턴스 단위로 적용되며, 전역이 아닌 anthropic.Anthropic() 인스턴스 생성 시 설정합니다. 따라서 동일 프로세스 내 여러 클라이언트 객체가 서로 간섭 없이 각각 다른 한도를 가질 수 있습니다.

이 기능을 필요로 하는 사용 사례는 크게 두 가지입니다. 첫 번째는 대용량 문서 파이프라인입니다. 수백 페이지짜리 PDF나 밀도 높은 데이터 내보내기 파일을 API에 전송하는 법률·연구·엔지니어링 워크플로우는 기존에 사전 분할 또는 외부 분리 단계를 거쳐야 했습니다. 클라이언트별 상한을 높이면 전처리 레이어를 단순화할 수 있습니다. 두 번째는 그 반대 경우로, 엣지 배포·샌드박스 러너·고빈도 큐 워커처럼 속도 제한이나 리소스 제약이 있는 환경입니다. 이런 환경에서는 기본값보다 낮은 상한을 강제해 실수로 대용량 파일이 업로드되어 쿼터를 소진하거나 예기치 않은 지연이 발생하는 것을 막을 수 있습니다.

인스턴스별 범위 지정이 핵심 설계 세부 사항입니다. 여러 Anthropic 클라이언트 객체를 유지하는 애플리케이션—멀티테넌트 서비스나 병렬 파이프라인 아키텍처에서 흔한 패턴—은 프로세스 격리나 커스텀 업로드 미들웨어 없이도 클라이언트마다 다른 업로드 상한을 지정할 수 있습니다. 한 클라이언트는 대용량 문서 수집을 처리하고, 같은 프로세스에서 실행되는 다른 클라이언트는 고빈도 소용량 호출에 엄격한 상한을 적용하는 식입니다. 정확한 생성자 파라미터 이름은 SDK CHANGELOG의 PR #1825 병합 노트에 있으며, 업그레이드 후 help(anthropic.Anthropic)를 실행하면 바로 확인할 수 있습니다.

실전에서의 작업 중간 명령 주입

대화 중간 system 블록을 사용하면 대화 시작 시의 최상위 system 필드뿐 아니라, messages 배열 내 임의의 위치에 system 역할 항목을 추가할 수 있습니다 . 이 기능은 모델의 동작 제약 조건을 대화가 이미 진행 중인 상태에서도 업데이트해야 하는 장기 실행 에이전트 파이프라인을 위한 것으로, 프롬프트 캐시를 깨거나 가짜 user 턴을 통해 업데이트를 우회하는 방식을 피할 수 있습니다.

기존 우회 방법은 업데이트된 지침을 user 역할 턴으로 주입하는 것이었습니다. 즉, user 역할을 시스템 수준 제약의 사이드 채널로 활용하는 방식이었습니다. 이 방법에는 두 가지 구체적인 문제가 있었습니다. 실제 사용자 메시지가 아닌 턴이 대화 기록을 오염시켜 재현, 감사, 파인튜닝 데이터 준비를 복잡하게 만들었습니다. 또한 user 채널을 통해 주입된 시스템 명령은 API 수준과 추론 수준 모두에서 잘못된 추상화이므로, 모델이 사용자 요청과 시스템 수준 제약 사이의 의미적 경계를 혼동할 위험도 있었습니다.

대표적인 사용 사례는 도구 호출을 실행하고 결과에서 새로운 환경 상태를 받는 에이전트 파이프라인입니다. 예를 들어 코드 실행 에이전트가 런타임 오류를 통해 대상 환경의 Python 버전을 파악했다고 가정해 보겠습니다. 이전에는 "Python 3.11에 맞게 조정하라"는 지침을 user 턴이나 다음 메시지 콘텐츠 앞부분에 끼워 넣어야 했습니다. 대화 중간 system 주입을 사용하면 도구 결과 뒤에 올바른 system 항목으로 추가할 수 있습니다:

messages = [
    {"role": "user", "content": "Analyze this codebase and suggest refactors."},
    {"role": "assistant", "content": "...", "tool_use": [...]},
    {"role": "tool", "tool_use_id": "...", "content": tool_result},
    # Inject updated constraint after learning the runtime environment
    {"role": "system", "content": "Target runtime is Python 3.11. Avoid 3.12-only syntax."},
]
response = client.messages.create(
    model="claude-opus-4-8",
    messages=messages,
    max_tokens=2048,
)

프로덕션 사용 시 열린 질문은 프롬프트 캐시와의 상호작용입니다. 이 기능은 대화 중간에 system 항목을 삽입해도 이전 메시지 블록의 캐시 히트가 무효화되지 않도록 설계되었습니다. Anthropic API의 캐시 적격성은 접두사 일치에 따라 결정되며, 새로 추가된 system 항목과 그 이후 메시지만 캐시된 접두사 범위 밖으로 나가는 것이 의도입니다. 그러나 이 동작은 현재 제공되는 v0.105.0 릴리스 노트에 공식적으로 문서화되어 있지 않습니다. 비용에 민감한 파이프라인에서 캐시 보존에 의존하기 전에 스테이징 환경에서 동작을 검증하십시오. 대표적인 대화에서 중간 system 항목 추가 전후로 usage.input_tokens_details.cache_read_input_tokens를 로깅해 이전 블록이 계속 캐시 히트를 받는지 확인하세요.

이틀 만에 세 버전: 0.105.0에서 0.105.2까지

0.105.x 라인은 이틀에 걸쳐 세 버전을 거쳤습니다. 2026년 5월 28일에 0.105.0이, 2026년 5월 29일에 0.105.1과 0.105.2가 함께 출시되었습니다 . 이러한 릴리스 주기는 주요 모델 출시 이후 전형적인 패턴입니다. 초기 릴리스는 모델 가용 시점에 맞추고, 이후 몇 시간 동안 프로덕션 트래픽을 만나면서 소규모 수정이 누적됩니다. 세 버전 모두에서 호환성을 깨는 변경 사항은 없었습니다 .

"Claude Opus 4.8은 오늘부터 Claude API, Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry 전반에 걸쳐 이용 가능합니다." — Anthropic, Claude Opus 4.8 출시 포스트

결정론적 빌드가 필요한 팀에게 실용적인 핀 권장 사항은 anthropic>=0.105.1,<0.106입니다. >=0.105.1 하한은 Trusted Publishing 전환 이전의 0.105.0을 제외합니다. <0.106 상한은 모델 문자열 추가나 아직 테스트 스위트에서 검증하지 않은 API 표면 변경이 포함될 수 있는 다음 마이너 버전의 자동 업데이트를 방지합니다. Anthropic이 0.105.2 릴리스 노트를 게시하고 통합 테스트를 통과하면, 그에 맞춰 핀을 올리거나 완화하십시오.

패치 릴리스 주기가 자동으로 처리하지 않는 한 가지 작업 항목은 샌드박스 스크립트 이름 변경입니다. pip install --upgrade anthropic으로 패키지를 업그레이드해도 CI 설정, 셸 스크립트, 코드형 인프라에서 참조하는 스크립트 경로 이름은 자동으로 바뀌지 않습니다. 업그레이드 절차의 일환으로 private-sandbox-worker를 명시적으로 grep하여 확인하십시오.

신뢰된 게시(Trusted Publishing)와 PyPI 배포 방식 전환

v0.105.1의 유일한 변경 사항은 anthropic PyPI 패키지 배포 방식을 장기 유효 API 토큰에서 신뢰된 게시(Trusted Publishing)로 전환한 것입니다. 이는 OIDC 기반 메커니즘으로, GitHub Actions 워크플로 자체가 릴리스마다 단기 유효 ID 토큰을 발급합니다. 사용자 영향은 없습니다. pip install anthropic==0.105.1은 이전 릴리스와 동일하게 동작하며, 변경 사항은 전적으로 Anthropic의 퍼블리셔 측에만 적용됩니다.

신뢰된 게시 방식을 도입하면 기존에 GitHub Actions 시크릿에 보관해야 했던 정적 PyPI API 토큰이 필요 없어집니다. 기존 방식에서는 시크릿이 유출될 경우 공격자가 악성 패키지 버전을 게시할 수 있었습니다. OIDC 기반 게시 방식에서는 릴리스마다 단일 워크플로 실행에만 유효하고 특정 저장소 및 워크플로 파일에만 적용되는 토큰을 사용하므로, 탈취·교체·실수로 커밋될 정적 자격증명이 존재하지 않습니다. 토큰은 릴리스 시점에 CI 환경이 발급하며 재사용이 불가합니다.

PyPI 신뢰된 게시는 2023년부터 제공되어 현재 주요 Python 패키지의 표준 관행으로 자리 잡았습니다. Anthropic이 0.105.1에서 이를 채택함으로써 SDK가 현행 공급망 보안 모범 사례에 부합하게 되었습니다. SBOM(소프트웨어 구성 명세서) 감사나 의존성 출처 검사를 수행하는 경우, GitHub Actions 워크플로가 생성한 0.105.1 빌드 증명(attestation)을 PyPI의 출처 API를 통해 확인할 수 있습니다. 서드파티 의존성의 공급망을 세밀하게 추적한다면 해당 도구와 연동할 가치가 있습니다.

0.105.x 업그레이드: 설치 및 검증

0.105.x 라인의 모든 변경 사항은 추가(additive) 방식으로, 업그레이드 시 기존 코드가 깨지지 않습니다. 아래 단계에서는 설치, 핵심 기능을 위한 스모크 테스트, 저장소에서 처리해야 할 비코드 변경 사항 체크리스트를 다룹니다.

설치:

# 0.105.x 라인의 최신 패치
pip install --upgrade anthropic

# 재현 가능한 환경을 위한 버전 고정
pip install "anthropic>=0.105.1,<0.106"

스모크 테스트 — 새 모델 및 output_tokens_details:

import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=64,
    messages=[{"role": "user", "content": "Ping"}],
)

print(response.usage)
details = getattr(response.usage, "output_tokens_details", None)
if details:
    print("output_tokens_details:", details)
else:
    print("output_tokens_details not present for this response type")

업그레이드 체크리스트:

• pip install "anthropic>=0.105.1,<0.106"를 실행하고 pip show anthropic으로 설치된 버전을 확인합니다.
• 저장소에서 private-sandbox-worker를 검색하여 모든 스크립트, Makefile, CI 설정에서 self-hosted-sandbox-worker로 교체합니다 .
• 확장 사고(extended thinking)를 사용하는 경우, 테스트 실행 시 response.usage.output_tokens_details를 로깅하고 원본 객체의 하위 필드를 확인합니다.
• 커스텀 파일 업로드 한도가 필요하다면, help(anthropic.Anthropic)에서 새 생성자 파라미터를 확인하고 클라이언트 인스턴스별로 설정합니다.
• 현재 가공된 user 역할 턴으로 시스템 지침을 주입하고 있다면, messages 배열의 적절한 system 역할 항목을 사용하도록 리팩터링합니다.
• v0.105.2 릴리스 노트 및 output_tokens_details 스키마 공식 문서는 SDK CHANGELOG를 모니터링합니다.

자주 묻는 질문

usage.output_tokens_details에는 실제로 무엇이 담겨 있나요?

usage.output_tokens_details는 출력 토큰 소비를 유형별로 구분해 보여주는 중첩 객체입니다. 주로 확장 사고(extended thinking) 중에 생성된 추론(thinking) 토큰과 일반 텍스트 출력 토큰을 분리합니다. 이는 usage.input_tokens_details가 캐시 읽기·쓰기 입력 토큰 수를 분류하는 방식과 대칭을 이룹니다. 하위 필드의 정확한 이름은 아직 공식 API 레퍼런스에 공개되지 않았습니다 . 실제 스키마를 확인하려면 확장 사고를 활성화한 상태로 요청을 보내 원시 response.usage 객체를 캡처해 출력해 보세요. 필드 유무는 응답 유형에 따라 달라질 수 있습니다. 스키마가 정식으로 문서화되기 전까지는 프로덕션 코드에서 getattr(response.usage, "output_tokens_details", None)와 같은 방어적 접근 패턴을 사용하세요.

업그레이드 후 Python에서 claude-opus-4-8을 호출하는 방법은?

anthropic>=0.105.0으로 업그레이드한 뒤, client.messages.create() 호출에서 model="claude-opus-4-8"을 전달하면 됩니다. 호스팅된 Claude API를 사용하는 경우 그 외 변경은 필요하지 않습니다. Claude Opus 4.8은 Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry를 통해서도 이용 가능합니다 . 호스팅 API의 엔드포인트 URL은 변경할 필요가 없습니다. 표준 모드 요금은 입력 토큰 100만 개당 $5, 출력 토큰 100만 개당 $25이며, 빠른 모드는 입력 100만 개당 $10, 출력 100만 개당 $50입니다 . 모델 전체 기능과 벤치마크 데이터는 Claude Opus 모델 페이지를 참고하세요.

v0.105.1과 v0.105.2에서 변경된 사항은?

2026년 5월 29일 출시된 v0.105.1 은 PyPI 배포 방식을 Trusted Publishing으로 전환했습니다. 이는 장기 유효 API 토큰을 OIDC 기반 인증으로 대체하는 공급망 보안 개선입니다. API 인터페이스 변경은 없으며 패키지 기능은 0.105.0과 동일합니다. 마찬가지로 2026년 5월 29일 출시된 v0.105.2 는 이 글을 작성하는 시점 기준으로 공개된 변경 로그가 없습니다. 0.105.2로의 업그레이드는 안전합니다—브레이킹 체인지가 보고된 바 없습니다—다만 Anthropic이 릴리스 노트를 공개하기 전까지는 미검증 내부 수정으로 간주하세요.

대화 중간에 system 항목을 삽입하면 프롬프트 캐시 히트가 깨지나요?

이 기능은 messages 배열 중간에 새 system 역할 항목을 삽입해도 이전 대화 블록의 프롬프트 캐시 히트가 무효화되지 않도록 설계되어 있습니다. Anthropic API의 캐시 적격성은 정확한 접두사 일치로 결정되며, 새 system 항목과 그 이후 메시지만 캐시된 접두사 범위 밖으로 벗어나는 것이 설계 의도입니다. 다만 이 동작은 v0.105.0 릴리스 노트에 공식적으로 문서화되어 있지 않습니다. 비용에 민감한 파이프라인에 이 패턴을 적용하기 전에 스테이징에서 검증하세요. 동일한 대화에 mid-turn system 항목이 있는 경우와 없는 경우 각각 usage.input_tokens_details.cache_read_input_tokens를 로깅해, 이전 블록이 프로덕션에서 캐시 히트를 계속 받는지 확인한 뒤 캐시 보존에 의존하세요.

클라이언트별로 파일 업로드 크기 제한을 설정하는 방법은?

anthropic.Anthropic()을 인스턴스화할 때 생성자 인수로 크기 상한을 전달하세요. 정확한 파라미터 이름은 SDK CHANGELOG의 PR #1825 병합 노트에 있습니다. 제한이 클라이언트 인스턴스 단위로 적용되므로, 같은 Python 프로세스 내에 여러 클라이언트 객체가 서로 간섭 없이 각기 다른 제한을 가질 수 있습니다. 대용량 문서 수집을 위한 높은 상한의 클라이언트와 속도 제한이 걸린 큐 워커를 위한 낮은 상한의 클라이언트를 하나의 애플리케이션에 깔끔하게 공존시킬 수 있습니다. 이 제한은 호출별 파라미터가 아닌 클라이언트 수준 설정이므로, 해당 클라이언트 인스턴스를 통해 이루어지는 모든 업로드에 일률적으로 적용됩니다.

0.106.x를 앞두고 주목할 사항

0.105.x 릴리스는 지속적으로 주시할 만한 여러 흐름을 만들어냈습니다. usage.output_tokens_details 스키마가 가장 시급합니다. Anthropic이 공식 문서에 하위 필드 이름을 공개하는 시점에 맞춰 로깅 및 비용 귀속 파이프라인을 업데이트해야 합니다. 0.105.1의 Trusted Publishing 전환은 일회성 이벤트이지만, 이제 SDK의 빌드 증명을 PyPI 출처 API로 검증할 수 있게 되었습니다. Python 의존성 그래프에 대해 SBOM 또는 공급망 감사를 수행하는 팀에게 유용한 신호가 됩니다.

모델 측면에서 Claude Opus 4.8은 주목할 만한 벤치마크 향상을 보여줍니다. SWE-bench Pro 69.2% (Opus 4.7의 64.3%에서 상승 ), SWE-bench Verified 88.6% , USAMO 2026 수학 96.7% 를 기록했습니다. 100만 토큰 기준 장문 맥락 GraphWalks F1은 68.1% 로, 이전 버전의 40.3%에서 큰 폭으로 올랐습니다. 이는 장기 자율 실행에서의 mid-task 지시 주입 기능과 직접적으로 시너지를 발휘하는 향상입니다. Opus 4.7을 사용 중인 팀이라면 모델 문자열 하나만 바꾸면 업그레이드가 완료되며, 나머지는 SDK가 처리합니다.

에이전틱 패턴이 성숙해감에 따라 대화 중간 system 블록 기능의 채택도 늘어날 것으로 보입니다. 툴 사용 워크플로를 구축하는 팀은 일찍부터 주입 전략을 정의해두는 것이 좋습니다. 파이프라인의 어느 단계에서 system 항목 추가가 허용되는지, 어떤 형식 제약이 적용되는지, 스테이징에서 캐시 동작을 어떻게 검증할지를 미리 규약으로 정립해 두면, 패턴이 코드베이스 전반에 퍼진 뒤 소급 적용하는 것보다 훨씬 수월합니다.

마지막 업데이트: 2026-05-29. v0.105.0, v0.105.1, v0.105.2 릴리스 노트 및 Claude Opus 4.8 출시 발표를 기반으로 작성되었습니다. usage.output_tokens_details의 하위 필드 스키마와 v0.105.2 변경 로그는 Anthropic의 공식 문서화를 기다리고 있습니다.