Anthropic Python SDK 1.0 마이그레이션: 직접 하거나 Claude Code로

Python 프로젝트를 anthropic 0.x에서 1.0으로 옮기는 작업은 설치 명령 하나, 즉 pip install --upgrade "anthropic>=1,<2"를 실행한 뒤 정해진 호환성 깨짐 목록을 한 번 훑는 것으로 끝납니다: HTTP 계층은 이제 httpx2 위에서 돌아가고, 비동기 .with_raw_response 리더는 코루틴이 되었으며, Text Completions와 temperature/top_p/top_k 파라미터는 사라졌고, AnthropicBedrock은 리전 없이는 생성되지 않습니다.¹ 공식 마이그레이션 가이드를 보며 그 목록을 직접 처리하거나, Claude Code가 /claude-api upgrade python으로 편집하게 한 뒤 diff를 검토하세요.¹³ Claude Code 릴리스 노트는 이 명령을 /claude-api upgrade라고 부르고, 마이그레이션 가이드는 python 인수를 덧붙이는데, 실제로 입력할 형태는 후자입니다.¹³ 두 경로 모두 같은 곳에 도착하며, 아래 글은 anthropic 1.0.0(2026년 8월 20일 PyPI 릴리스, 8월 25일 확인) 기준으로 각 경로를 다룹니다.² {.answer-block}

요약

• pip install --upgrade "anthropic>=1,<2"로 업그레이드한 뒤 pyright나 mypy를 실행하세요. 마이그레이션 가이드에 따르면 타입 검사기가 거의 모든 호환성 깨짐을 잡아내므로, 그 자체가 준비된 체크리스트가 됩니다.¹
• Python 3.10이 새로운 최소 버전입니다. 환경에서 달라지는 것은 그것뿐이며, SDK는 여전히 Pydantic v1과 v2를 지원합니다.¹
• httpx가 httpx2로 바뀌었습니다. timeout=30.0 같은 단순 값은 그대로 동작하지만, 클라이언트에 넘기는 httpx 객체는 httpx2에서 만든 것이어야 하고, httpx를 패치하는 라이브러리는 httpx2.alias_httpx()를 호출하기 전까지 SDK 요청을 보지 못합니다.¹
• 제거됨: Text Completions, 샘플링 파라미터, output_format의 스키마 dict. client.completions.create(), temperature, top_p, top_k는 사라졌고, 스키마 dict는 output_config={"format": {...}}로 옮겨갑니다.¹
• Claude Code v2.1.239(2026년 8월 21일)에 /claude-api upgrade가 추가되어 Python 프로젝트를 anthropic 0.x에서 1.x로 마이그레이션합니다.³ 그 결과물은 다른 자동 마이그레이션과 똑같이 다루세요: 커밋하기 전에 diff를 읽으세요.

anthropic 1.0으로 업그레이드하면 무엇이 깨지나요?

여섯 가지 변경이 무게의 대부분을 차지하는데, 저는 가이드의 빠른 참조를 이 여섯 가지로 압축했고 더 작은 제거 항목은 그 뒤에 따릅니다.¹ 가장 큰 변경에는 분명한 이유가 있습니다: SDK의 HTTP 계층이 더 이상 활발히 유지보수되지 않는 httpx에서, Pydantic 팀이 유지보수하며 같은 클래스, 같은 동작에 보안 수정까지 포함한 API 호환 포크 httpx2로 옮겨갔기 때문입니다.¹

더 작은 제거 항목과 동작 변경 하나가 함께 따라오며, 각각 대체 방법이 있습니다:¹

마지막 행은 조용히 발목을 잡습니다: default_headers={"USER-AGENT": "my-app/1.0"}는 이제 둘 다 보내는 대신 SDK 자체의 User-Agent를 대체합니다.¹

직접 마이그레이션하려면 어떻게 하나요?

세 단계를 순서대로 진행합니다: 업그레이드하고, 타입 검사기가 깨진 곳을 찾게 한 뒤, 범주별로 고칩니다.

pip install --upgrade "anthropic>=1,<2"
pyright   # or mypy

가장 요란하게 실패하는 부분이므로 httpx import부터 먼저 고치세요. SDK 자체의 재내보내기(anthropic.Timeout, anthropic.DefaultHttpxClient, anthropic.DefaultAsyncHttpxClient, anthropic.DefaultAioHttpClient)는 이미 httpx2를 가리키며 그대로 동작하고, httpx에서 직접 만든 객체만 별칭이 필요합니다.¹

# Before
import httpx
from anthropic import Anthropic, DefaultHttpxClient

client = Anthropic(
    timeout=httpx.Timeout(60.0, connect=5.0),
    http_client=DefaultHttpxClient(
        proxy="http://my.proxy.example",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

# After
import httpx2 as httpx  # or `import httpx2` and rename the references
from anthropic import Anthropic, DefaultHttpxClient

client = Anthropic(
    timeout=httpx.Timeout(60.0, connect=5.0),
    http_client=DefaultHttpxClient(
        proxy="http://my.proxy.example",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

애플리케이션의 다른 코드가 여전히 httpx를 import하면서 SDK와 클라이언트나 예외 타입을 공유하거나, OpenTelemetry의 HTTPXClientInstrumentor, Sentry의 httpx 통합, respx, pytest-httpx, vcrpy를 사용한다면, 진입점 맨 위에서 httpx2.alias_httpx()를 한 번 호출하세요. 이 호출은 무엇이든 httpx를 import하기 전에 실행되어야 하고(그렇지 않으면 RuntimeError가 발생합니다), 가이드는 이를 애플리케이션 전용으로 못 박습니다: 라이브러리가 사용자를 대신해 호출해서는 절대 안 됩니다.¹ pytest에서는 가이드가 제시하는 가장 덜 침습적인 방법이 초기 플러그인으로, httpx2.alias_httpx()를 호출하는 tests/_alias_httpx.py 모듈을 pyproject.toml에 등록해 respx, pytest-httpx, 테스트 모듈보다 먼저 로드되게 하는 것입니다:¹

# tests/_alias_httpx.py
import httpx2

httpx2.alias_httpx()  # makes `import httpx` / `import httpcore` resolve to httpx2 / httpcore2

# pyproject.toml
[tool.pytest.ini_options]
addopts = "-p tests._alias_httpx"
pythonpath = ["."]

응답과 오류 객체도 이제 httpx2 타입입니다. 패키지 변경은 넘기는 값뿐 아니라 SDK가 반환하는 값에도 적용됩니다. APIStatusError.response, APIConnectionError.request, raw response의 response.http_response / .headers / .url, 그리고 사용자 정의 http_client 이벤트 훅이 받는 response= 인수는 모두 httpx2 객체입니다. 속성은 이전과 정확히 같으므로, httpx.Response / httpx.Request / httpx.Headers를 이름으로 지정하는 isinstance 검사와 타입 애너테이션만 httpx2로 바꾸면 됩니다.¹ isinstance 경우는 한 번 더 살펴볼 가치가 있습니다. 가이드는 그런 검사를 바꿔야 한다고만 말하는데,¹ 그것이 중요한 이유는 httpx2.alias_httpx()가 httpx를 httpx2로 해석되게 만들지 않은 한, 예전 패키지를 기준으로 한 isinstance(err.response, httpx.Response) 같은 검사가 예외 없이 False를 반환하고 핸들러가 해당 분기를 건너뛰기 때문입니다.

# Before
def log_failure(err: anthropic.APIStatusError) -> None:
    response: httpx.Response = err.response
    print(response.status_code, response.headers.get("request-id"))


# After
def log_failure(err: anthropic.APIStatusError) -> None:
    response: httpx2.Response = err.response
    print(response.status_code, response.headers.get("request-id"))

다음은 raw response 리더입니다. .with_raw_response는 예전에 두 클라이언트 모두에서 LegacyAPIResponse를 반환했지만, 이제는 .with_streaming_response가 이미 사용하던 것과 같은 APIResponse / AsyncAPIResponse 클래스를 반환합니다.¹

다음은 제거된 파라미터입니다. 현재 모델은 temperature, top_p, top_k를 사용하지 않으므로, 생성된 메서드는 더 이상 이를 받지 않습니다. 이 변경 이전의 모델은 extra_body를 통해 여전히 이 값들을 존중하며, SDK는 이를 요청 JSON에 그대로 병합합니다.¹

# Before
client.messages.create(..., model="claude-sonnet-4-6", temperature=0.2)

# After
client.messages.create(..., model="claude-sonnet-4-6", extra_body={"temperature": 0.2})

스키마 dict도 같은 방식으로 옮겨갑니다: beta.messages.create()의 output_format={"type": "json_schema", "schema": ...}는 output_config={"format": {"type": "json_schema", "schema": ...}}가 되고, parse() / stream() / count_tokens() / tool_runner() 헬퍼는 클래스에 대해 output_format=Order를 유지하되 거기에 스키마 dict를 넣으면 이제 TypeError가 발생합니다.¹

Bedrock으로 마무리합니다. AnthropicBedrock과 AsyncAnthropicBedrock은 예전에 경고를 기록하고 us-east-1로 대체했지만, 이제는 생성 시 ValueError를 발생시킵니다. 리전은 aws_region=, 그다음 AWS_REGION / AWS_DEFAULT_REGION, 그다음 주어진 aws_profile의 boto3 세션 순으로 결정됩니다.¹ 또한 SDK는 예전에 내보내던 알 수 없는 Bedrock 스트리밍 이벤트를 이제 건너뛰는데, 알려진 유일한 경우는 amazon-bedrock-invocationMetrics입니다.¹

Claude Code로 마이그레이션하려면 어떻게 하나요?

마이그레이션 가이드 자체가 지름길을 알려줍니다: 프로젝트에서 /claude-api upgrade python을 실행하고 diff를 검토하세요.¹ 이 명령이 들어온 곳은 2026년 8월 21일에 릴리스된 Claude Code v2.1.239이며, 릴리스 노트 전문은 다음과 같습니다. “Added /claude-api upgrade to migrate Python projects from anthropic 0.x to 1.x, and updated the skill’s Python reference for 1.x (timeouts use anthropic.Timeout, not httpx.Timeout)”.³

그 문장이 검증된 표면의 전부입니다: 프로젝트의 0.x 사용을 1.x로 마이그레이션하는 /claude-api 스킬 명령이라는 것입니다. 이 명령이 편집 내용을 어떻게 고르는지에 대한 추가 문서는 찾지 못했으므로, 정확히 그것으로, 즉 diff를 검토해야 하는 자동 마이그레이션으로 취급하세요. v2.1.239 이상으로 업데이트하고(claude update, 또는 설치 및 업데이트 참조), 프로젝트 루트에서 세션을 열어 실행하세요:

/claude-api upgrade python

그다음, 기여자의 마이그레이션 PR에 하는 것과 똑같은 검토로, diff를 hunk 단위로 읽고 타입 검사기를 돌리고 테스트 스위트를 실행하세요. 여기서는 타입 검사 단계가 평소보다 더 중요한데, 1.0의 호환성 깨짐은 거의 모두 타입 오류이고 그 검사는 누가 편집했는지를 따지지 않기 때문입니다.¹ 릴리스 노트가 짚는 한 가지 세부 사항, 즉 httpx.Timeout이 아닌 anthropic.Timeout은 가이드와 일치합니다: 그 재내보내기는 이미 httpx2를 가리킵니다.¹³

Claude Code가 처음이신가요? 빠른 시작은 첫 세션을, 전체 가이드는 번들 스킬과 슬래시 명령을 다룹니다.

자주 묻는 질문

anthropic 1.0은 여전히 Pydantic v1을 지원하나요?

네. SDK는 여전히 Pydantic v1과 v2를 지원하며, Python 3.10 최소 버전이 유일한 환경 변경입니다.¹

업그레이드 후 OpenTelemetry나 respx 설정이 SDK 요청을 보지 못하는 이유는 무엇인가요?

그 라이브러리들은 SDK가 더 이상 사용하지 않는 httpx를 패치합니다. 무엇이든 httpx를 import하기 전에 httpx2.alias_httpx()를 호출하세요. 그러면 프로세스 전체에서 import httpx가 httpx2로 해석됩니다.¹

구형 모델에 여전히 temperature를 넘길 수 있나요?

네, extra_body={"temperature": 0.2}를 통해 가능하며, SDK가 이를 요청 JSON에 병합합니다. messages.batches.create()의 경우 요청의 params dict에 키를 바로 넣으세요.¹

tool_runner의 클라이언트 측 컴팩션은 무엇으로 대체되었나요?

서버 측 컴팩션입니다: tool_runner()에 betas=["compact-2026-01-12"]와 context_management={"edits": [{"type": "compact_20260112", "trigger": {"type": "input_tokens", "value": 100_000}}]}를 넘기세요. 가이드의 예시에서는 이 조합이 compaction_control={"enabled": True, "context_token_threshold": 100_000}를 대체하며, 트리거 임계값은 최소 50,000 토큰이어야 합니다.¹

requirements에서 httpx_aiohttp를 제거해야 하나요?

네. anthropic[aiohttp]와 http_client=DefaultAioHttpClient()는 이전과 같이 동작하지만, 이제 SDK 안에 포함되어 배포되므로 해당 extra는 더 이상 httpx_aiohttp를 설치하지 않습니다.¹

핵심 요약

애플리케이션 개발자라면: - "anthropic>=1,<2"로 고정하고, 타입 검사기를 실행한 뒤, httpx import, raw response의 await, 제거된 파라미터, Bedrock 리전 순으로 범주별로 고치세요.¹ - 프로세스 안의 다른 무언가가 SDK와 httpx 객체를 공유하거나 httpx를 계측한다면, 진입점 첫 줄에 httpx2.alias_httpx()를 두세요.¹

라이브러리 유지보수자라면: - 라이브러리 안에서는 절대 httpx2.alias_httpx()를 호출하지 말고, 대신 import에 별칭을 두세요(import httpx2 as httpx).¹ - anthropic.Transport / ProxiesTypes를 버리고 httpx2.BaseTransport / httpx2.Proxy를 사용하세요.¹

Claude Code를 사용하는 팀이라면: - v2.1.239 이상으로 업데이트하고 프로젝트 루트에서 /claude-api upgrade python을 실행한 뒤, diff를 검토하고 커밋 전에 타입 검사기와 테스트를 실행하세요.¹³

참고 자료