Anthropic SDK 1.0.0, 그리고 조용히 어긋나는 것들

Anthropic의 API SDK가 8월 20일에 1.0.0을 달았어요. 버전 번호만 보면 성숙 선언인데, 정작 읽어야 할 건 그 하루 전날입니다. 8월 19일에 Files와 Skills API가 동시에 베타를 벗었고, 클라이언트 툴셋 두 개가 새로 들어왔고, Managed Agents의 셀프 호스팅 환경에 메모리 스토어가 붙었어요. 5월부터 계속 넓히기만 하던 표면을 한 주 만에 굳힌 셈이죠.

5월에 벌어진 세 가지

이 흐름의 시작은 5월 11일이에요. 그때 Managed Agents가 SDK에 들어오면서 에이전트 루프와 도구 실행 컨테이너를 Anthropic이 대신 굴리는 선택지가 생겼어요. 여드레 뒤엔 셀프 호스팅 샌드박스가 추가되면서 같은 오케스트레이션을 쓰되 도구 실행만 자기 인프라로 가져오는 절충안이 열렸고요.

같은 날 Anthropic은 Stainless를 인수했어요. SDK 자동 생성 파이프라인을 내재화한 건데, 8월에 벌어진 일을 보면 그 인수의 쓰임새가 선명해집니다. Python과 TypeScript SDK가 같은 날 같은 변경 사항을 담아 나왔고, 문구까지 한 글자도 다르지 않아요. 여러 언어의 메이저 버전을 한꺼번에 밀어 올리는 게 우연히 되는 일은 아니에요.

8월 19일, 베타 딱지를 떼다

Files API와 Skills API가 Claude API에서 정식 출시로 내려왔어요. files-api-2025-04-14와 skills-2025-10-02 베타 헤더가 더는 필요 없고, 업로드한 파일을 참조하는 Messages 요청에도, container로 Skill을 불러오는 요청에도 헤더가 안 붙습니다. SDK에는 client.files와 client.skills가 최상위 네임스페이스로 새로 생겼어요.

client.beta.files와 client.beta.skills는 그대로 남아 있어요. 지우는 대신 같은 경로에 ?beta=true를 붙이는 쪽으로 바꿔서, 기존 코드는 안 깨집니다. 다만 GA 이름을 비워주느라 베타 타입들이 DeletedFile에서 BetaDeletedFile로, FileMetadata에서 BetaFileMetadata로 바뀌었어요. 이 이름들을 직접 임포트하고 있었다면 그건 깨져요.

같은 날 들어온 브라우저 툴셋

컴퓨터 사용도 이날 computer_toolset_20260801로 정식 출시됐어요. tools에 항목 하나만 넣으면 screenshot, left_click, type, zoom을 포함한 17개 멤버 툴이 한꺼번에 붙습니다. 예전 단일 툴 시절의 display_number나 enable_zoom 같은 파라미터는 이제 거부당하고, 줌은 configs.zoom.enabled로 옮겨가 기본 활성이에요.

같이 나온 브라우저 툴셋은 컴퓨터 사용의 새 버전이 아니라 첫 버전인 별개 도구예요. 둘 다 클라이언트 툴셋이라 Anthropic은 멤버 툴의 스키마만 정의하고 실제 실행은 전부 애플리케이션 쪽에서 일어납니다. 멤버 31개 중 27개가 기본 활성이고, file_upload, read_console, read_network, javascript_exec 넷은 켜야 붙어요.

컴퓨터 사용과 갈리는 지점은 접근성 트리예요. 데스크톱 전체를 스크린샷과 좌표로 다루는 대신, 페이지의 요소와 폼과 탭을 구조로 읽고 각 요소에 참조를 붙여 좌표 없이 클릭할 수 있어요. read_page, find, get_page_text, form_input, 탭 관리가 그 구조 기반 도구들이고요. 물론 좌표도 그대로 지원해요. 캔버스나 임베드 영상처럼 접근성 트리가 설명하지 못하는 영역이 있으니까요. Vercept 인수 때 이야기했던 컴퓨터 사용 역량 강화가 제품 형태로 도착한 게 이 두 툴셋입니다. 지원 모델은 Fable 5, Mythos 5, Opus 5, Sonnet 5, Opus 4.8 다섯 개이고, Claude API와 Google Cloud에서 쓸 수 있어요.

그리고 1.0.0

다음 날인 8월 20일, Python SDK가 1.0.0을 달았어요. GitHub 릴리스 노트에 적힌 파괴적 변경은 딱 한 줄이고 나머지는 MIGRATION.md로 넘깁니다. 핵심은 HTTP 계층이 httpx에서 httpx2로 옮겨간 것. httpx가 더는 활발히 유지보수되지 않아서, Pydantic 팀이 유지하는 API 호환 포크로 갈아탄 거예요. 최소 Python 버전은 3.9에서 3.10으로 올라갔고, Text Completions API는 통째로 사라졌고, .with_raw_response가 LegacyAPIResponse 대신 APIResponse를 돌려주면서 .text와 .content가 속성에서 메서드가 됐어요. 비동기 클라이언트에서는 본문을 읽는 게 await 대상이 되고요.

국내 팀 기준으로 실제 걸림돌은 아마 Python 3.10 쪽일 거예요. 3.9에 묶인 사내 이미지에서는 pip이 그냥 마지막 0.x를 계속 물어와서 아무것도 안 깨지고, 그래서 올릴 이유도 안 생깁니다. 그 상태가 길어지면 이번 GA 전환의 새 응답 필드들과 툴셋을 못 쓰는 채로 남아요.

조용히 어긋나는 쪽

여기까지가 릴리스 노트가 말해주는 내용이고, 실제로 시간을 쓰게 되는 건 다른 데예요.

httpx2 전환에서 요란하게 깨지는 경로는 오히려 안전합니다. 구 패키지의 httpx.Client를 http_client=로 넘기면 생성 시점에 바로 TypeError가 나요. 문서도 "그래서 이건 조용히 실패할 수 없다"고 못 박아 뒀고요. 문제는 조용한 쪽이에요. respx, pytest-httpx, vcrpy, OpenTelemetry의 HTTPXClientInstrumentor, Sentry의 httpx 통합은 전부 httpx 패키지를 패치하는데, SDK는 이제 그걸 안 씁니다. 임포트도 되고 에러도 안 나고 테스트도 통과하는데, SDK 트래픽만 안 보여요. 스텁한 줄 알았던 요청이 실제로 나가고 있을 수 있다는 뜻이죠. 문서가 권하는 해결책은 httpx2.alias_httpx()를 다른 무엇보다 먼저 호출하는 것인데, 이건 애플리케이션 진입점 전용이에요. 라이브러리가 사용자 대신 부르면 안 됩니다.

GA 전환에도 비슷한 비대칭이 있어요. Skills는 옛 베타 헤더를 계속 보내도 정말 아무 일도 안 일어나요. 반면 Files는 헤더를 보내면 동작은 하되 이전 응답 포맷에 고정됩니다. expires_at 같은 새 필드가 안 오고 페이지네이션도 예전 방식이에요. 헤더를 지우는 걸 나중으로 미룬 코드는 에러 없이 옛날 응답을 계속 받는 셈인데, 릴리스 노트 한 줄은 두 API를 나란히 묶어서 이 차이를 안 알려줍니다.

셀프 호스팅 샌드박스의 메모리도 결이 같아요. 클라우드 환경에서는 read_only 스토어가 파일시스템 수준에서 강제돼서 쓰기 자체가 거부되는데, 셀프 호스팅에서는 워커의 도구 레벨에서만 막혀요. write와 edit는 거부하지만 bash는 로컬 사본을 그대로 고칠 수 있습니다. 고친 내용이 스토어로 올라가진 않아요. 그런데 다음 동기화 때 되돌려지지도 않아서, 스토어 쪽에서 그 메모리가 바뀌기 전까지 그 세션의 이후 도구 호출들은 계속 수정된 사본을 읽습니다. 읽기 전용이라고 적어둔 것이 세션 안에서는 읽기 전용이 아닌 구간이 생기는 거예요.

세 가지 다 성격이 같아요. 코드를 그대로 뒀을 때 에러 없이 다르게 동작하는 변경들이고, 버전 번호는 이걸 알려주지 않습니다. 1.0.0이라는 숫자가 주는 안정감은 API 표면에 대한 약속이지, 그 아래 이음매까지 덮어주는 건 아니에요. 마이그레이션 체크리스트를 만든다면 굵게 표시된 파괴적 변경보다 이쪽을 먼저 훑는 게 나을 것 같아요.

---

근거가 된 소식: anthropic-sdk-python v1.0.0, v0.124.0, v0.125.0, anthropic-sdk-typescript sdk-v0.119.0. 세부 동작은 SDK 저장소의 MIGRATION.md와 Anthropic 공식 문서(컴퓨터 사용·브라우저 사용 툴, Managed Agents 셀프 호스팅 샌드박스 문서)를 2026년 8월 27일 기준으로 확인했어요.