Claude Python SDK 1.0 전환: httpx2와 제거된 옵션이 배포 파이프라인에 주는 영향

Claude Python SDK 1.0은 단순한 버전 숫자 변경이 아닙니다. Python 3.10 이상을 요구하고, HTTP 계층을 httpx에서 httpx2로 옮기고, 오래 남아 있던 Text Completions API와 일부 Messages 파라미터를 제거합니다. Claude API를 제품 백엔드, 내부 자동화, 평가 파이프라인에 붙여 둔 팀이라면 “pip 업데이트하면 되겠지”로 넘기면 안 됩니다.

이번 변경의 핵심 검색 의도는 명확합니다. “Claude Python SDK 1.0 마이그레이션을 어디서부터 확인해야 하는가”입니다. 답은 코드 검색, 테스트 격리, 관측성 패치 확인, 배포 순서 분리입니다. 특히 tracing, mocking, custom transport를 쓰는 팀은 httpx2 전환이 생각보다 넓게 번질 수 있습니다.

무엇이 바뀌었나

공식 릴리스 노트 기준으로 Python SDK 1.0은 HTTP 레이어를 httpx2로 이동했습니다. httpx2는 httpx API와 호환되는 유지보수 포크지만, “이름만 바뀐 동일 패키지”로 보면 위험합니다. 커스텀 http_client, Timeout, transport 객체를 생성하는 코드가 있다면 import 위치와 타입 기대값을 확인해야 합니다.

또 하나는 오래된 표면 제거입니다. legacy Text Completions API가 빠졌고, Messages 메서드에서 temperature, top_p, top_k 같은 파라미터가 제거되었습니다. 이미 모델별 기본값이나 reasoning 중심 API로 옮겨간 팀은 영향이 작겠지만, 사내 래퍼가 모든 모델 호출에 공통 옵션을 끼워 넣는 구조라면 런타임 오류가 납니다.

비동기 클라이언트의 .with_raw_response 결과도 await response.parse()가 필요합니다. 이건 테스트에서 놓치기 쉽습니다. 성공 응답은 왔는데 파싱 코드가 coroutine을 그대로 다루거나, 예외 핸들링에서 raw body만 보는 코드가 깨질 수 있습니다.

개발팀이 먼저 확인할 영향 범위

첫 번째는 공통 Claude 클라이언트 래퍼입니다. 대부분의 팀은 서비스 코드가 직접 SDK를 부르지 않고 ClaudeClient, LLMProvider, AnthropicGateway 같은 얇은 계층을 둡니다. 이 계층에서 timeout, retry, tracing, request id, cost tag를 붙입니다. SDK 1.0 전환은 이 파일 1개만 바꾸면 끝나는 것처럼 보이지만, 실제 영향은 테스트 더블과 모니터링까지 이어집니다.

두 번째는 CI의 Python 버전입니다. SDK가 Python 3.10 이상을 요구하므로, Lambda 런타임, GitHub Actions 이미지, Docker base image가 3.9 이하인지 확인해야 합니다. 특히 오래된 배치 작업은 운영 서버보다 CI가 먼저 깨지는 경우가 많습니다.

세 번째는 Bedrock 연동입니다. AnthropicBedrock이 AWS region 미설정 시 us-east-1로 암묵 기본값을 쓰지 않고 오류를 내도록 바뀌었습니다. 이건 좋은 변경입니다. 하지만 기존 운영에서 region 누락을 기본값에 기대고 있었다면 배포 직후 장애가 납니다.

마이그레이션을 안전하게 나누는 방법

권장 순서는 “SDK 업그레이드 브랜치 → 래퍼 호환 계층 → 테스트 더블 수정 → 스테이징 트래픽 복제”입니다. 한 번에 기능 코드까지 고치면 원인 분리가 어려워집니다.

먼저 저장소에서 다음 키워드를 검색합니다.

rg "TextCompletions|completions|temperature|top_p|top_k|with_raw_response|httpx|AnthropicBedrock|ANTHROPIC" .

검색 결과를 세 그룹으로 나눕니다. 첫째, 제거된 API를 직접 쓰는 코드. 둘째, 아직 지원되지만 import나 타입이 바뀌는 코드. 셋째, 테스트와 관측성 코드입니다. 실무에서는 세 번째를 빼먹습니다. 그런데 tracing 라이브러리가 httpx를 monkey patch하는 구조라면 SDK 호출이 갑자기 추적에서 사라질 수 있습니다.

httpx patch를 쓰는 팀은 httpx2.alias_httpx()를 검토해야 합니다. 단, 전역 alias는 영향이 넓습니다. 단위 테스트에서만 켜는지, 앱 부팅 초기에 켜는지, 다른 HTTP 클라이언트와 충돌하지 않는지 확인해야 합니다.

장애로 이어지는 흔한 패턴

가장 흔한 패턴은 “옵션 병합 함수”입니다. 예를 들어 모든 LLM 호출에 {temperature: 0.2, top_p: 0.9}를 기본으로 붙이는 코드가 있습니다. SDK 1.0 이후 Messages 메서드가 해당 옵션을 받지 않으면 요청 생성 단계에서 깨집니다. 해결은 모델별 옵션 스키마를 분리하는 것입니다.

두 번째는 raw response 파싱입니다. API gateway에서 status, headers, request id를 기록하려고 .with_raw_response를 쓰는 팀은 많습니다. 비동기 코드에서 parse 호출 방식이 바뀌면 로깅은 성공했는데 본문 처리만 실패하는 애매한 상태가 됩니다.

세 번째는 배치 작업입니다. 운영 API 서버는 잘 테스트하지만, 야간 요약, 리포트 생성, 평가 데이터셋 재채점 같은 작업은 오래된 Docker 이미지에서 돌아갑니다. Python 3.10 요구사항 때문에 여기서 먼저 실패할 수 있습니다.

운영 전환 기준

SDK 1.0 전환은 “새 기능 적용”이 아니라 “기초 의존성 교체”로 다루는 편이 안전합니다. 배포 기준도 기능 QA보다 호환성 QA에 가깝게 잡아야 합니다.

확인할 지표는 4개입니다. 호출 성공률, 평균 지연 시간, retry 비율, 추적 누락률입니다. 모델 응답 품질은 이번 변경의 직접 대상이 아닙니다. 대신 HTTP 계층과 파라미터 처리, region 설정, response parsing이 핵심입니다.

스테이징에서는 실제 운영 프롬프트 20~50개를 재생해 보세요. 단순 ping 테스트는 충분하지 않습니다. 파일 첨부, tool use, long context, streaming, raw response, timeout이 섞인 케이스를 골라야 합니다.

실행 체크리스트

• Python 런타임이 3.10 이상인지 확인합니다.
• Claude SDK를 직접 부르는 파일과 사내 래퍼를 분리해 검색합니다.
• temperature, top_p, top_k를 공통 옵션으로 주입하는 코드를 제거하거나 모델별로 분기합니다.
• .with_raw_response를 쓰는 비동기 코드에 await response.parse()가 반영됐는지 테스트합니다.
• httpx tracing 또는 mocking을 쓰면 httpx2 전환 후 추적 데이터가 유지되는지 확인합니다.
• Bedrock 사용 시 AWS region을 환경변수나 설정 파일에 명시합니다.
• 배치 작업과 CI 이미지의 Python 버전을 같이 올립니다.
• 배포 후 호출 성공률, retry 비율, tracing 누락률을 최소 24시간 봅니다.

Claude Python SDK 1.0은 장기적으로는 좋은 정리입니다. 오래된 API와 암묵 기본값을 줄이면 운영 예측 가능성이 올라갑니다. 다만 그 이득은 마이그레이션을 명시적으로 했을 때만 얻습니다. 이번 업데이트는 “requirements.txt 한 줄 수정”이 아니라 “LLM 호출 경계 정리” 작업으로 잡는 것이 맞습니다.