AIREITERAnthropic Python SDK v1.0이 2026년 8월 20일 PyPI에 공개됐습니다. 대부분의 호출 코드는 그대로 동작하지만, 이번 업그레이드에서 가장 위험한 부분은 오류가 바로 드러나지 않는다는 데 있습니다. HTTP 계층이 httpx에서 httpx2로 바뀌면서, httpx를 패치하는 트레이싱·APM 에이전트와 테스트 목이 계속 실행되더라도 SDK 요청은 조용히 하나도 기록하지 않을 수 있습니다. 업그레이드 후 테스트가 통과했다는 사실만으로는 안심하기 어렵습니다.
이틀 동안 세 번 릴리스한 뒤 1.0이 나왔다
anthropic의 PyPI 릴리스 기록은 꽤 분명합니다. 0.123.0, 0.124.0, 0.125.0이 2026년 8월 19일 연달아 출시됐고, 다음 날인 8월 20일 표준 Trusted Publishing 방식으로 1.0.0이 공개됐습니다.
공식 릴리스 노트에서 밝힌 변경 사항은 다음과 같습니다.
- HTTP 계층이 유지 관리되고 API 호환성을 갖춘 포크인
httpx2로 변경됩니다. - Python 3.10 이상이 필요합니다. 분류자에는 3.10부터 3.14까지가 등록돼 있습니다.
- 오랫동안 사용 중단이 예고됐던 기능이 제거됩니다. 레거시 Text Completions API, Messages 메서드의
temperature·top_p·top_k파라미터, 툴 러너의 클라이언트 측compaction_control이 대상입니다. - AWS 리전이 설정되지 않은 상태에서
AnthropicBedrock을 사용하면, 이제us-east-1로 조용히 기본 설정하는 대신 오류를 발생시킵니다.
GitHub의 v1.0.0 태그는 이번 버전을 “upgrade to httpx2 and some minor breaking changes”라고 설명합니다. 릴리스 노트에서 놓치기 쉬운 변화도 있습니다. parse, stream, tool_runner 헬퍼에 붙어 있던 베타 경고가 사라졌습니다. 1.0으로 올라가면서 베타라는 단서까지 없어진 만큼, Anthropic이 이제 이 API 영역을 안정 버전으로 취급한다고 볼 수 있습니다.
httpx에서 httpx2로 바뀌면서 실제로 달라지는 점
클라이언트를 기본 방식으로만 만들었다면 달라지는 것이 없습니다. 하지만 HTTP 계층을 직접 건드린다면 이야기가 완전히 달라집니다.
기준은 클라이언트에 무엇을 전달하느냐입니다. 숫자 값은 계속 작동합니다. 예를 들어 Anthropic(timeout=30.0)은 이전과 똑같이 동작합니다. 반면 객체는 그렇지 않습니다. 일반적인 httpx.Client를 http_client=로 넘기면 첫 요청 시점이 아니라 클라이언트 생성 단계에서 TypeError가 발생합니다. 커스텀 클라이언트·타임아웃·트랜스포트는 이제 httpx2로 만들어야 하며, 기존의 httpx.Timeout 객체는 anthropic.Timeout(또는 httpx2.Timeout)으로 바꿔야 합니다.
# 0.x
client = Anthropic(http_client=httpx.Client(proxy="http://proxy:8080"))
# 1.0
client = Anthropic(http_client=DefaultHttpxClient(proxy="http://proxy:8080"))DefaultHttpxClient와 DefaultAsyncHttpxClient는 이름과 동작이 그대로입니다. 이제 내부 HTTP 계층만 httpx2로 바뀌었을 뿐, SDK가 권장하는 타임아웃·커넥션 풀·리디렉션 기본값은 그대로 유지합니다. 플랫폼 DevX 엔지니어 @cjav_dev의 Anthropic 직원 공지도 출발점으로 공식 MIGRATION.md를 안내합니다. 이 문서에는 모든 변경 사항과 전후 코드 예제가 정리돼 있습니다.
이런 전환은 전례가 없는 일이 아닙니다. OpenAI Python SDK의 httpx2 마이그레이션 가이드가 먼저 같은 경로를 거쳤습니다. 동일한 포크, DefaultHttpx2Client 헬퍼 패턴, respx 호환성 경고까지 닮아 있습니다. 이미 openai를 마이그레이션한 팀이라면 기존 작업 방식을 거의 그대로 재활용할 수 있습니다.
v1.0에서 제거된 기능 전체 목록
| v1.0에서 제거된 항목 | 대신 사용할 것 |
|---|---|
client.completions.create() (Text Completions) | client.messages.create() |
HUMAN_PROMPT / AI_PROMPT 상수 | Messages 형식의 콘텐츠 블록 |
메서드 시그니처의 temperature, top_p, top_k | 여전히 해당 값을 받는 레거시 모델에는 extra_body={"temperature": ...} |
messages.parse(stream=True) | messages.stream(...) |
tool_runner(compaction_control=...) | 서버 측 컴팩션 설정 |
anthropic.Transport, anthropic.ProxiesTypes 별칭 | httpx2 트랜스포트 타입 |
저수준 요청 메서드의 body= | content= |
베타 API의 output_format 스키마 딕셔너리 | output_config={"format": ...} (구조화된 출력 헬퍼는 여전히 output_format=MyModel을 지원) |
isinstance(stream, anthropic.Stream) 검사 | 구체적인 MessageStream 타입 확인 |
표에 덧붙일 내용이 두 가지 있습니다. Pydantic v1과 v2는 모두 계속 지원되므로 모델 클래스는 그대로 사용해도 됩니다. 또 헤더 병합이 이제 대소문자를 구분하지 않습니다. 대소문자만 다르게 같은 헤더를 두 번 설정한 코드가 있다면 동작이 달라질 수 있습니다. 흔한 경우는 아니지만, 문제가 발생해도 오류가 나지 않을 수 있는 엣지 케이스입니다.
원시 응답을 사용하는 비동기 코드에서만 드러나는 변화
.with_raw_response를 사용하는 경우에만 비동기 변경 사항이 크게 문제 됩니다. 비동기 클라이언트에서는 이제 parse(), read(), text(), json()에 모두 await가 필요합니다. 동기 클라이언트에서는 .text와 .content가 프로퍼티에서 메서드로 바뀌었습니다. 둘 다 import 시점에는 실패하지 않습니다. 동기 코드는 attribute error를 내며 즉시 드러나지만, 비동기 코드는 await하지 않은 코루틴이 실행되지 않은 채 남아 더 조용하게 문제를 일으킬 수 있습니다.
관련 변화로 예외와 원시 결과에 포함된 요청·응답 객체도 이제 httpx2 타입입니다. 대부분의 속성 접근 방식은 같지만, isinstance(x, httpx.Response) 검사와 타입 어노테이션은 수정해야 합니다. 이런 부분은 pyright와 mypy가 정확히 잡아낼 수 있습니다.
눈치채기 어려운 마이그레이션 실패
변경 로그에서는 한 문장으로 축약되지만, 모니터링 대시보드에서는 큰 문제로 돌아오는 부분입니다. Anthropic의 마이그레이션 가이드에 따르면 httpx를 패치해 HTTP 트래픽을 관찰하거나 모킹하는 도구인 OpenTelemetry, Sentry, respx, pytest-httpx, vcrpy는 업그레이드 후에도 계속 실행되면서 SDK 요청만 조용히 놓칠 수 있습니다. 이 도구들은 import도 되고 실행도 되며 보고서도 생성합니다. 다만 더 이상 패치 대상 라이브러리를 거치지 않는 트래픽은 보지 못할 뿐입니다. 실제 가로채기가 일어났는지 검증하지 않는 테스트라면, 목에 요청이 도달하지 않아 아무것도 실패하지 않는 ‘무의미한 통과’가 발생할 수 있습니다.
해결책은 httpx2.alias_httpx()입니다. 애플리케이션이나 테스트 시작 지점에서 가장 먼저 호출해야 하며, Python SDK 문서는 어떤 httpx import보다 먼저 호출하라고 안내합니다. 이 함수는 httpx2를 httpx라는 이름으로 연결해 패치 도구가 계속 작동하게 합니다. 단, 마이그레이션 가이드는 이 함수를 라이브러리 코드에서 호출하지 말고 애플리케이션 진입점에서만 호출하라고 경고합니다.
“정상적으로 시작됐다는 사실만으로 AI 호출이 계속 트레이싱되거나 모킹되고 있다고 단정할 수는 없습니다.” — @MarMarLabs, 출시 다음 날 게시
이 게시물은 전체 내용을 읽어볼 가치가 있습니다. 업그레이드 후 실제로 트레이싱된 호출 하나와 모킹된 호출 하나가 등록되는지 의도적으로 확인하는 것을 첫 번째 마이그레이션 테스트로 삼으라는 내용입니다. 같은 스레드에서는 httpx2로 수동 전환해야 하는 커스텀 트랜스포트와, 설치 단계에서 오래된 CI 이미지의 Python 3.10 하한 요구 사항을 충족하지 못하는 문제도 조용한 위험으로 지적합니다.
수정하지 않아도 계속 동작하는 코드
많은 코드베이스에서는 솔직히 할 일이 없을 수도 있습니다. 커스텀 클라이언트·트랜스포트·타임아웃 객체를 직접 만들지 않는다면 HTTP 마이그레이션의 영향을 받지 않습니다. 다음 항목도 변하지 않습니다.
client.messages.create(...)에 일반 파라미터만 전달하는 호출: 같은 요청과 같은 응답 모델을 사용합니다.- 숫자로 지정한 타임아웃과 SDK 기본값: 연결 오류, 408, 409, 429, 5xx에 대해 지수 백오프 방식으로 2회 재시도하며, 기본 타임아웃은 10분입니다.
base_url라우팅: SDK를 게이트웨이나 AIReiter의 Claude API 엔드포인트 같은 API 호환 릴레이로 연결해도 v1.0은 이 계층에 아무런 변화를 주지 않습니다. 바뀐 것은 URL이 아니라 클라이언트입니다.- Pydantic v1·v2 모델, SSE 스트리밍 헬퍼, 파일 업로드 인터페이스
단, Python 3.10 이상이라는 필수 조건은 반드시 충족해야 합니다. ‘안전한’ 목록의 나머지 항목도 이 조건을 통과한다는 전제에서만 유효합니다.
코드 리뷰에서도 설득력 있는 마이그레이션 순서
- 먼저 버전을 의도적으로 고정합니다. 아직 준비되지 않았다면
anthropic>=0.125,<1로 작업 일정을 잡을 때까지 현재 버전을 유지할 수 있습니다. - 코드베이스에서
import httpx와httpx.를 검색합니다. SDK와 맞물리는 코드에 해당 문자열이 있다면 모두 마이그레이션 대상입니다. - Claude Code에서
/claude-api upgrade python을 실행합니다. @cjav_dev의 릴리스 공지가 권장하는 명령으로, 프로젝트에서 변경될 부분을 diff 형태로 생성합니다. - 커스텀 클라이언트·트랜스포트·타임아웃을
httpx2또는DefaultHttpxClient헬퍼로 다시 만듭니다. httpx를 패치하는 코드가 있다면 애플리케이션 진입점에httpx2.alias_httpx()를 추가합니다.- pyright 또는 mypy를 실행합니다. httpx2 타입 변경으로 인한 어노테이션 및
isinstance오류가 드러납니다. - CI에서는 테스트 스위트마다 트레이싱된 요청 하나와 모킹된 요청 하나가 실제로 등록되는지 검증합니다. 시작 로그가 정상이라는 사실은 증거가 아닙니다.
Anthropic Python SDK v1.0 FAQ
Anthropic Python SDK v1은 실제로 출시됐나요? 아직 0.x 아닌가요?
출시됐습니다. anthropic 1.0.0은 2026년 8월 20일 PyPI에 공개됐고, GitHub에서 v1.0.0 태그가 붙었습니다. 전날에는 0.125.0이 출시됐습니다. 현재 PyPI 프로젝트 페이지도 0.x 사용자에게 v1 마이그레이션 가이드를 안내합니다.
v1.0 이후 temperature, top_p, top_k는 어떻게 전달하나요?
메서드 시그니처에서 제거됐습니다. 서버 측에서 여전히 해당 값을 받는 레거시 모델이라면 extra_body={"temperature": 0.7} 형태로 전달하면 됩니다. 다만 현재 모델은 기본값이 아닌 샘플링 값을 사용하면 400을 반환합니다. 이는 SDK가 아니라 모델 계층에서 발생한 변경입니다.
respx, pytest-httpx, vcrpy 테스트는 계속 작동하나요?
SDK 기본 클라이언트에서는 그대로 작동하지 않습니다. 게다가 오류도 발생하지 않고 아무 요청도 매칭하지 못합니다. 테스트 시작 단계에서 어떤 httpx import보다 먼저 httpx2.alias_httpx()를 호출하거나, 모킹을 httpx2.MockTransport로 옮겨야 합니다. 레거시 httpx만 패치하는 respx 버전은 SDK 트래픽을 가로챌 수 없습니다.
/claude-api upgrade python은 무엇을 하나요?
Claude Code 명령어입니다. Anthropic DevX 엔지니어 @cjav_dev의 공지에서 권장한 명령으로, anthropic 0.x를 사용하는 프로젝트를 스캔해 import, 타임아웃 객체, 원시 응답 호출 등 마이그레이션이 필요한 부분을 diff로 생성합니다. 트레이스백을 보고 뒤늦게 발견하는 대신 변경 사항을 검토할 수 있습니다.
0.125에 고정할까, 1.0으로 갈까
모든 팀에 통하는 정답은 없습니다. 실제 선택지는 이렇습니다. 1.0 미만을 유지하면 기존의 목·트레이서·커스텀 트랜스포트를 그대로 보존할 수 있습니다. 하지만 안정화 이전 SDK에 계속 머물게 되고, 버전 정책상 마이너 릴리스에서도 하위 호환성이 깨질 수 있습니다. 게다가 의존 중인 completions와 샘플링 파라미터는 이제 공식적으로 수명이 끝난 기능입니다. 1.0으로 옮기면 안정화된 비베타 API를 얻는 대신, 언젠가가 아니라 지금 HTTP 계층 전체를 점검해야 합니다. 결국 직접 관리하는 HTTP 계층의 규모가 판단 기준입니다. 일반적인 Anthropic() 호출 하나만 있는 서비스라면 쉽게 업그레이드할 수 있지만, 커스텀 트랜스포트와 respx 테스트 스위트를 운영하는 플랫폼이라면 배포 전에 조용한 실패 여부를 반드시 확인해야 합니다.
함께 읽어볼 만한 글로는 같은 주에 베타를 벗어난 Skills API와 8월 10일 영구 가격으로 전환된 Sonnet 5가 있습니다. 모두 같은 시기의 Claude Platform 릴리스에서 나온 변화입니다.